<?xml version="1.0" encoding="UTF-8" ?>

<!-- Example of a dSurvey descriptor file.
   
  Note: the Create An Instrument dSurvey utility will automatically create a "dsurvey descriptor file",
        and let's the administrator set most of the parameters. This automatically created descriptor file
        will be essentially identical to the descriptor file described below.

  First important proviso: Instrument, and session, descriptor files are XML files.
                           So XML syntax rules must be followed!
      
   When a session is created, the instrument descriptor file (for the instrument the session is based on)
   is read, slightly modified, and saved as the sessions's descriptor file.  
   The administrator would then modify the session's descriptor file BEFORE any participants join.

   Thus, the instrument descriptor file can be thought of as the "default" descriptor file for sessions that
   use this intrument.

   Restating:
      The instrument descriptor file specifies basic variables used by all sessions that "use" this instrument.
      And the session descriptor file specifies the values to be used for a particular session.

    Basic syntax:
        <?xml version="1.0" encoding="UTF-8" ?>
          <descriptor>
                <desc value="var1"> a description </desc>
                <var1> value </var1>
                                ..,
                <desc value="varN"> a description </desc>
                <varN> value </varrN>
          </descriptor>

    Each variable is specified as an XML element, using:
                <varName> a value </varName>

    The following  variables are recognized: note that that the names are case InSensitive!

        ALLOWED_USERS       ::  On generic "join a session page": require a username and password. Assign a REFID.
        DESCRIPTION         ::  1 sentence desccription of this instrument
        FILE                ::  Specify several files to copy to the session specific directory
        DEBUG_MODE           ::  Amount of debug information displayed to partcipants
        GET_CONTACT         ::  On generic "join a session page": include a "contact info" input field
        GET_NICKNAME        ::   On generic "join a session page": include a "nickname" input field
        HOME_PAGE           ::  The URL to the home page for sessions based on this instrument
        HOW_ASSIGN          ::  How to assign "reference" data to participants
        ID_WHICH            ::  Get clientID from server, or generate internally, or ask participant to supply
        MAX_USERS           ::  Max # of users to accept
        MESSAGE_OPTIONS     ::  Initialization options for dSurvey's message feature
        NAME                ::  Instrument name (used to resolve default directories and files)
        NAME_CHECK          ::  Do not permit users with the same NAME
        REJOIN              ::  participants allowed to rejoin (not currently implemented)
        RESUBMIT            ::  participants are allowed to resubmit their information for a single round
        REF_MAX             ::  Generate a REFID between 1 and REF_MAX, or 0 to use control-panel assignation
        SCENARIO_FILE       ::  Name of the XML file to use for the instrument and session "default" scenario
        USE_PASSWORD        ::  On generic "join a session page": require a password
        WINDOW              ::  Specifications for the window to open when a participant joins a session

    What these do is described below. But first, some extra comments on the DESC and FILE "variables".


  Notes on FILE

     The FILE variable can be specified multiple times, so it has a special syntax:
             <file name="1_word_name"  type="atype" contains="dataTypeList">relative_file_name</param_file>
     where:
         name="1_word_name"  : used to display descriptions (see DESC below)
         type="atype"       : atype can be "DATA" or "CONTROL". 
                          If type="DATA" is used, these files will be editable by the "modify parameter files"  administative action. 
         contains="dataTypeList" : Optional. dataTypeList can contain one or more of the following: GENERAL, REFERENCE,  and/or USERS
                          If NOT specified, the file may contain all of these three datatypes.
                          If specified, any dataType NOT specified in the list is assumed NOT to occur in the file.
                          dataTypeList is ONLY used for atype="DATA" files. It is used as a shortcut by the modify-input files action.
                              Hence, not including it will NOT effect program functionality, though it might make the administrative 
                              screens more cluttered. 

     Notes:
        * for an allowed-users file, then "contains" is not used.
        *  relative_file_name should be a file in this instrument's directory. It will be copied
           to a newly created session's directory. The copy in the session's directory can then be modified.

  More on DESC

       DESC is optional, and special. It can be used many times. And it does NOT specify a variable.
       Intead, it is used to specify a "description".
          These variable descriptions are used by dSurvey administrative programs.
          Specifically, <DESC> is used by administrative programs that display, and allow you to edit,  session descriptor files.

       DESC  syntax:
          <DESC value="var_name" > A short description </desc>
      
       The "var_name" is matched either to:
           i) the  tagname (the "varname" in a <varname>...</varname>
       or
           ii) the name attribute of a <file> ... <file>

      The "short description" in a DESC should NOT contain HTML markup.
       However, you can include the following html-shortcuts (they are case inSENSITIVE):
          [P] : same as <p/>
          [BR] : same as <br />

  Note on usage:
       Each instrument must have an "instrument descriptor file".
       When a session is created for this instrument, a copy of this "instrument descriptor file"
       is created and saved to the "sessions" area. This copy is called the "session descriptor file"
       After creation, you can modify parameters in this session descriptor file.
       When a new participant joins, dSurvey's join feature will read this session descriptor file,
       using it's variables to dicate how to join the session.
       Once the session is joined, the session descriptor file is NO LONGER used: in fact, variables
       defined in the session-descriptor file are not readily accessible by dSurvey's client-side
       javascript procedures (there are a few exception: variables that are explicitily included
       in the "join" request).
       In contrast, the control panel does have access to the session descriptor file (using the
       "sessionNode" DOM object)

-->


<descriptor>                            <!-- start the XML file with some node (the exact nodeName doesn't matter -->


<!-- (ALLOWED_USERS)
   ALLOWED_USERS is used to specify user's names, and their passwords (and their "REFIDS").
   Two forms can be used:
        i)  Specify an XML file containing userName information file
       ii)  Specify it as a space delimited string

   i) The syntax should be
        <allowed_users>=file</allowed_users>
     This will read an allowedUsers.xml (in the session specific directory).

     Notes:
        *   For more information on the structure of this file, see allowedUsers.xml in the docs directory.
        *   If there is no allowedUsers.xml file (and it MUST have that name) in the session's directory,
            and if ALLOWED_USERS='=FILE', a crytpic error message will appear on the client's screen whenever a join is attempted.
        *   Hint: the create-allowed-users utility can help you create a session specific allowed_users file.

 ii) Space delimited string.

   If not empty, only users with a (case sensitive) name in the space delimited ALLOWED_USERS list are 
   permitted to join the session.
   The name and passsword  can NOT contain a period, comma, ampersand (@),= sign, or colon (or, obviously, a space).

   Syntax: username:password=Refid     
   where the password and refid are optional.
   Thus, the following are legal. Note the special password values of "0" and "1":
          Moe
          Sam:tunaFish
          Alan:munchkin=5
          Peter=7
          Sue:0
          Juan:1

   Example:

        <allowed_users> charles jacob:ty40  phillip  matt:sterm3=12  vince=3 </allowed_users>

   Notes:
     *  If you want to use user-specific passwords, you MUST specify USE_PASSWORD='something', it doesn't matter what the
        "something" is (i.e.; use_password='x' will work). If you do NOT specify this, then the password input box will
         not be shown on the join-a-session form!

    *  A password of "0" (as specified using ":0") means this participant does NOT need a password.
    *  A password of "1" (as specified using ":1") means "use the default password"
    *  If : is not specified, use the default password.  In other words ":1" and NOT specifying ":" are synonymous.

    *   If ALLOWED_USERS is '', or 0, then any username can join (though they will need to enter a password, if USE_PASSWORD is specified)

    *   To reiterate, when  USE_PASSWORD is specified, then the value of USE_PASSWORD is used only if NO user-specific password is specified
        (of if ":1" is specified. If a user-specific password is specified (for a given user), the value of USE_PASSWORD is ignored.

    * If a REFID (specified using =REFID) appears, then the value after the = sign is used as the reference ID.  
       This is used regardless of the value of REF_MAX or HOW_ASSIGN. 
       Actually, using =REFID with a non-zero value of REF_MAX can be done, but is not recommended.
       It will work, but not necessarily in a predictable fashion.

-->
<desc value="ALLOWED_USERS">Space delimited list of allowed users and (optionally) their passwords and reference-id.
[p] Syntax: user1:pwd1 user2 user3:pwd3 user4:pwd4=refid4
[br] To allow any user, enter 0 (or leave this blank).  
[p] To specify an XML file containing users, enter '=FILE' (without the quotes)
</desc>
<ALLOWED_USERS>0 </ALLOWED_USERS>



<!-- (DESCRIPTION)
  A short description of this survey instrument
-->
<desc value="description">  a one sentence description of this instrument </desc>
<description> ERS "CRP" experiment, 8/08 version. With risk experiment. </description>


<!-- (FILE)
     The following specify XML files that contain variables used to control the details of the instrument, 
     and that are used to assign participant specific values.
     In this example, two files are specified:
        i) A file that contains data that contains GENERAL information.
       ii) A file that contains data that contains REFERENCE information.

   Note: the default directory for the "relative files" specified by FILE: \www\dsurvey\instruments\NAME\
         (where NAME is the value of the <NAME> attribute discussed above).

-->
<desc value="parametersFile">File defining general parameters used in this instrument. A session specific copy will be made.   </desc>
<file name="parametersFile"  type="DATA" contains="GENERAL" >MySurvey_Params.xml</file>

<desc value="ticketData">Input file that contains reference data (used to specify values for each participant) </desc>
<file name="ticketData" type="DATA" contains="REFERENCE" > MySurvey_tickets.xml </file>

<!-- This specifies the control-panel program. -->
<desc value="controlFile"> The control panel program to use to manage sessions (that are created from this instrument)</desc>
<file name="controlFile"  type="CONTROL" >MySurvey_Control.xml</file>


<!-- (DEBUG_MODE)
   0/1/2 variable. 0: no debug info, 1: small debug info, 2: lots of debug info

  Note:
    * The screen seen by the client has a few debug links that are sort of hidden. These are meant for used
      by administrators and developers: they display information on load status, or display the source
      code of the current page and values of current variables.  To access these, you click on
      the appropriate places (the moving dots on initial load, the 'You are x' and the '..short descriptions
      are written here' footers), and they enter "debug" to the "which view" prompt box.
 
-->
<desc value="DEBUG_MODE"> How much debug info to show. 0:none, 1: small amount, 2: lots </desc>
<debug_mode>1</debug_mode>


<!-- (GET_CONTACT)
   0/1 variable. If 1, then when joining, ask the participant to provide contact info (in addition to a name). Otherwise, do NOT ask for contact info
-->
<desc value="GET_CONTACT"> If 1, then ask participants to provide contact info (in addition to a name)</desc>
<get_Contact>0</get_Contact>


<!-- (GET_NICKNAME)
   0/1 variable. If 1, then when joining, ask the participant to provide a nickname (in addition to a name). Otherwise, do NOT ask for a nickname
-->
<desc value="GET_NICKNAME"> If 1, then ask participants to provide a nickname (in addition to a name)</desc>
<get_NickName>0</get_NickName>

<!-- (HOW_ASSIGN)
  Specify how to assign participant specific values (from data in the obsData file)

  Allowed values are:

  0) NONE
     Do NOT assign variables (and their values) to participants. This is required if you don't bother
     creating (or saving) a REFERENCE data file (that is, if there is no participant-specific variables
     used by this instrument).
  a) 0, or blank
     Participants will be assigned data (from the REFERENCE data) in order of joining. That is, the first row read from the reference
     data files will be assigned to the first joiner, etc.
     If the number of "joiners" exceeds the number of rows,  a reference id of "0" is used.
  b) NAME=rNAME
     There must be a USER variable called "NAME". And there must be a "rName" reference variable.
     For each user, the value of the NAME variable will be matched against a REFERENCE row with the save value of its rName variable.
     For example:  NAME=REFNAME would match the NAME variable (say, as entered by the user when he joins) against a REFNAME variable
     specified in the REFERENCE dataset.
     Matches are case Insenstive, with  spaces stripped.
     If a match (the users NAME variable matches a rName) occurs, the corresponding row is used.
     If a match does NOT occur,   a reference id of "0" is used.
  c) STOP
     Once the number of joiners equals the number of rows in the reference database, a "-1" is assigned.
  d) 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.
  e) 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)
  f) 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

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

Note: if client side assignation of reference ID is enabled (if REF_MAX is not equal to 0), 
       then only CYCLE and RANDOM are supported. 

-->
<desc value="how_assign"> Specify how to assign  participant specific values (that is, what row to use from the data in the REFERENCE data file).
[p] Permitted values are: NONE, 0, userVarName=refVarName, STOP, CYCLE, RANDOM, or RANDOM_NOREP  </desc>
<HOW_ASSIGN>CYCLE</HOW_ASSIGN>


<!--  (HOME_PAGE)
   The HOME_PAGE is a URL that points to the "specification file" for this survey instrument.
    If set to 0 or '', then a default URL is used of the form: /dsurvey/instruments/instrumentName/instrumentName.html
-->
<desc value="home_page">The URL that points to the home page for sessions based on this instrument. Use 0 to use the default </desc>
<home_page>/dsurvey/mystuff/doit.html </home_page>


<!-- (ID_WHICH)
Dictates how a clientID is created.
  If 0, when a participant joins a session, the clientID is automatically generated  by the client.
  If 1, when a participant first joins a session, the clientID is obtained from the server.
  If 2, the participant enters one directly
  If "2 , message ", then participants enter one directly, and the "message" is displayed next to the input box
-->
<desc value="id_which"> 0=automatically generated by client; 1=clients retrieve id from server when they join session;  2=participant enters</desc>
<id_which>0</id_which>


<!-- (MAX_USERS)
      If a non-zero positive number is specified, then no more than MAX_USERS will be allowed to join: if this many users have already
      joined, future joiners will recieve an error message0
      If 0, or '', then no limit on the number of joiners.
      Note that the HOW_ASSIGN parameter is applied after participants have joined; and at that stage later joiners may be denied
      access. Thus you should be consistent in your uses of MAX_USERS and HOW_ASSIGN
-->
<desc value="max_users">Maximum number of participants for this survey. 0 means "no limit" </desc>
<max_users>20 </max_users>



<!-- (MESSAGE_OPTIONS)
A comma delimited string containing  instructions for the dSurvey message feature (participants). 
These are used to initialize a message_options control panel variable, which is included in
the <message> section of CAP files.
When a client reads a CAP file with a message_options variable, its value will be 
used to set message options (i.e.; they will override options set in the SPEC
files <init><message><options>).

To specify these options, use a space delimited string of one-word instructions.
The currently supported instructions include:

    notify : When a new message is retrieved, a screen message will be displayed informing the participant that a new message has arrived. This is ignored if polling is disabled.
  nonotify : Disable notification (the default)

    show : Display the message button, or its custom replacement (the default))
  noshow : Do not display the message button (or its custom replacement)

    enable : Enable message sending and recieving (the default) ; this does not imply a show (you must ALSO specify a SHOW)
   disable : Disable message sending and recieving; implies noshow
 notesonly : If specified, then disable sending and recieving messages, but enable the note feature


   sendAll  : Allow messages to be sent to anyone (the default)
    noSend  : Do not allow messages to be sent, but do allow reciept of messages
  adminSend : Do not allow messages to be sent to participants, but do allow messages to the administrator (adminSend trumps noSend).
  sendIf=equation : Allow message if equation is satisfied.  You can refer to "message variables" by
                   using messageVar('varname') (be sure to quote the variable name)
                   For example: sendIf= myGroup eq messageVar('mygroup')
                   (say, if mygroup was a user variable that was saved as a message variable)

  poll=nseconds : Controls how often messages are downloaded from the server.
                  By default, messages will be retrieved only when the participant specifically requests. 
                  If poll=nseconds is specified, then every nseconds messages will be downloaded from the server.
                  If poll=0, then this automatic downloading is disabled (the participant will have to specifically
                  request a message retrieval).
         nopoll : same as POLL=0 (the default) 

Examples: 
   enable ,show
   disable
   enable ,show, notify , poll=30
   enable , show , notify , sendIf= myage lt messageVar(groupAge)


-->
<desc value="message_options">Initialization instructions for the dSurvey message feature (participants)
Enter comma-delimited string of options. Options may be: NOTIFY, NOTIFY, SHOW, NOSHOW, ENABLE, DISABLE, NOTESONLY, 
SENDALL, NOSEND, ADMINSEND, SENDIF=logicalEquation, POLL=nseconds, NOPOLL.
Defaults are: NONOTIFY, SHOW, ENABLE, SENDALL, NOPOLL.
 </desc>
<message_options>enable show</message_options>


<!--  (NAME)
   NAME should be a 1 word name for this instrument.
   Typically, but not necessarily, it will be the same name as the "instrument descriptor" XML file
   NAME is used when resolving a variety of file and directory names: see INSTRUMENTS\INSTALL.TXT for the details

   Note: NAME can not be changed by the  "create instrument" utility
-->
<desc value="name"> The 1 word name of this instrument: used to find specification files, directories, etc. THIS IS NOT USED AS A SESSION NAME</desc>
   <name>MySurvey  </name>


<!--  (NAME_CHECK)
  Check to see if participant is already in this session.  This checks the  participants NAME against all names currently enrolled in the session
  (using a stripped, case-insensitive check). If a match is found, the participant is not allowed to join.
    NAME_CHECK:1       (perform the name check)
    NAME_CHECK:0           (do not : there can be several participants with the same name )
-->
<desc value="name_check">Set to 1 to check to see if a participant using this name is already enrolled in this session. </desc>
<name_check>0 </name_check>


<!-- (REF_MAX)
   REF_MAX is used to specify how to create a reference ID.

   REF_MAX can be:

         0           =  Control-panel assignation of reference data.  

         READ        = Use this if the largest recordID may change 
                       If READ is used, you will also need to specify a  saveRefMax attribute 
                       in <getParams> (in the control panel file)

         number gt 0 = Client side extraction.  
                       REF_MAX  should be the value of the largest recordID in the reference data.

                       When a client joins, the client will generate a REFID between 1 and REF_MAX :
                       using either a CYCLE or a RANDOM algorithim (as specified in HOW_ASSIGN)

-->
<desc value="ref_max">If using control-panel assignation of reference data, this should be 0.
If using client-extraction, this should the value of the largest ID in the reference data.
</desc>
<ref_max>0</ref_max>


<!-- (REJOIN)
   0/1 variable. If 1, allow participants to rejoin a survey session. If 0, do not.
        THIS IS NOT CURRENTLY IMPLEMENTED
-->
<desc value="rejoin"> Can the participant leave, and then rejoin, this session?
If yes, use a value of 1. Otherwise they can NOT rejoin </desc>
<rejoin> 1 </rejoin>


<!-- (RESUMBIT)
  A 0/1 variable. If 1, participants are allowed to resubmit information in a round. Typically, this means that
  the earlier submission will not be erased from the server-side database, but when a download of the data occurs
  the later submission will overwrite the earlier.
-->
<desc value="resubmit"> Can the participant submit data more than once per round?
1 for yes, otherwise only one submission per round is accepted </desc>
<resubmit> 0</resubmit>




<!--   (SCENARIO_FILE)
   The SCENARIO_FILE is the name of an XML file that should be used as the "instrument" and "session"
    default scenarios. Typically, this is the file specified in the 
        file name="parametersFile"  type="DATA" contains="GENERAL" 
    FILE specification (see above).
   
    If set to 0 or '', then  no default scenarios (for the instrument or the session) will be available

    Notes: 
       *  "scenarios" are used by control panels. 
       *   only specify a file name: include the .XML suffix, but NO path information
       *  the file name should point to a file (that contains GENERAL parameters)
       *  this file should be in the INSTRUMENTS\INAME path (where INAME is the name of the instrument)
       *  Reminder: when a new session is created, all FILEs specified (in FILE statements) will be copied
           to the sessions' directory (using the exact same name).
       *  Which is why the same name is used for the "instrument" default scenario, and the "session" default
          scenario. 
       *  And, when a session is first created, these 2 files (hence the scenarios will be identical.
       *  However, the "session" version of this file (hence the session default scenario)
           may be changed (say, by using the  Modify Parameters action on the administrator's page).

-->
<desc value="scenario_file">The XML file to use as the Instrument, or the Session, default scenario </desc>
<scenario_file>MySurvey_Params.xml </scenario_file>



<!--   (SMTP_GATEWAY, SMTP_NAME, SMTP_PASSWORD)
  dSurvey can send out email alerts (say, after results are submitted to the server).
  To do this one must have access to an STMP mail server.
  This means you must provide:
     SMTP_GATEWAY : the internet address of an SMTP server that you have "relay" rights on
                    (i.e.; smtp.myIsp.org)
     SMTP_USERNAME : the username of an account, on the SMTP server, that has "relay rights"
     SMTP_PASSWORD : the password of this username.
 Most SMTP servers will require some kind of authentication. If you are using an SMTP
 server that does not require authentication, you can leave the SMTP_USERNAME and SMTP_GATEWAY empty.

 Note that a dSurvey only supports the not-very-secure AUTH SIMPLE authentication.
-->

<smtp_gateway>
  <desc > The smtp_gateway should be the internet address of your smtp mail server (i.e.; smtp.myIsp.net).
         If 0, then email alerts will not be enabled.
         Note that for most stmp servers, you will also need to properly set the
         smtp_name and smtp_password parameters.
  </desc>
  <value>0</value>
</smtp_gateway>


<smtp_name>
  <descInfo>The name of your account on the smtp gateway. </descInfo>
  <desc >
     This smtp_name is combined with the smtp_passwordlogon to the smtp gateway (using an AUTH SIMPLE protocol).
  </desc>
  <value>0</value>
</smtp_name>


<smtp_password>
  <descInfo>The password for your account on the smtp gateway. </descInfo>
  <desc >
     This smtp_password combined with the smtp_name to logon to the smtp gateway (using an AUTH SIMPLE protocol).
  </desc>
  <value>0</value>
</smtp_password>




<!-- (USE_PASSWORD)
  If not empty (and not '0'),then ask for a password. The password entered must match the USE_PASSWORD (if it doesn't, the participant is
  asked to reenter the password).
  By default, this password is used for all users. However, if ALLOWED_USERS is specified, and a user has a password defined, then the user-specific
  password is used.
-->
<desc value="USE_PASSWORD">The default password (set to 0 if no default password is required) </desc>
<use_Password>0</use_Password>




<!-- (WINDOW)
   Specifications for new window to open when participant joins this session.
  When a participant joins a session, the base-page for this session is loaded and the dSurvey client software for this session will start.
  This can occur in the current window, or a new window can be opened.
  This parameter controls whether to open a new window, and the specifications for this new window
  Syntax:
        <window>0</window>  :: do NOT open a new window: use the current window
        <window>1</window>  :: open a new, "chromeless" window
        <window>specs</window> :: open a new window using the "specs"
  Specs should be window-opening specifications, as would be used in a call to the javascript window.open function.
  For example, the following could also be used to open a chromeless window: toolbar=0,location=0,directories=0,status=0,toolbar=0,scrollbars=1,resizable=1
-->

<desc value="WINDOW">Specifications for new window to open when participant joins this session. Leave blank, or set to 0, to use current window. 
[br] Example  (a no chrome window): toolbar=0,location=0,directories=0,status=0,toolbar=0,scrollbars=1,resizable=1
[br]Shortcut: for the above no chrome window, enter 1.
</desc>
<window>0</window>




</descriptor>                           <!-- and end the XML file properly -->

