# Survey Tool Operation

Steven R. Loomis srl@icu-project.org. Updated 2008 Feb 22
Copyright 2008 IBM and others. All Rights Reserved

## About This Document

This document is directed towards the Operation of the Survey Tool. Please see 'readme.txt' in this directory for the building and installation of the survey tool.

## Prerequisites

Read the readme.txt in this dir. You should have:

1. Survey Tool installed in a web container
2. Latest CLDR data available to ST
3. CLDR_VAP password set up (user 'admin@')
4. CLDR_SMTP / CLDR_FROM set for email access

## Overview of administrative interface

1. #### Login access

   You can log in as the Administrator account with the email address 'admin@' and the password specified in the CLDR_VAP parameter in the cldr.properties file.

   When logged in, you will see a red bar at the top of the page that says:

   > 'Be careful, you are an administrator!'

   This is here to warn you that some normal user safeguards are not in place,　and also that you have access to advanced functions. Also, it reminds you that　your votes have 'override' capability.

2. #### Administrative override

   As the administrative account has override capability, it is possible to break　ties. As well, another user named "Admin Override" was added, with level zero 　(admin). In theory it has full administrator access as well. However, we have given its access out to a select few TC members, with the express instruction　that they were not to play with any of the other buttons, but just to cast the　overriding votes where the TC had decided to do so.

3. #### SQL: "more than enough rope"

   The SQL interface provides access to more or less anything that the admin　interface does not cover. It is both powerful and dangerous and will be covered　separately. SQL access does not actually require a login, but uses a special URL which includes the admin password. So, SQL activity can be done without logging in if the URL is kept.

4. #### User panel

   The "Manage users for.." link works for the Admin user as it does for others,　however all users are visible, not just those of one organization. There are a few extra options, as well.

5. #### Administrative panel

   The "Admin" link in the top right corner brings up the "SurveyTool Administration" panel. It has two levels, the "main" level (fairly safe), and the "EXPERT" level (dangerous, possibly experimental). The EXPERT-ADMIN-use-only link brings up the additional items.

   As with SQL, Admin does not actually require a login, but uses a special URL which includes the admin password. So, Admin activity can be done without logging in if the URL is kept.

## Configuration

This section describes settings found in the `cldr.properties` file inside the cldr directory. SurveyTool must be restarted for these to take effect.

1. #### Officiality

   By default, the ST runs in "unofficial mode" and declares itself to be so with a banner. Setting `CLDR_OFFICIAL=yes` causes this banner to be hidden.

2. #### Phases and Version

   The "Phases" (vetting, submission, etc) are controlled by the `CLDR_PHASE` parameter. For example, set `CLDR_PHASE=SUBMIT` to use the Data Submission phase. As of this writing, the valid phases are: `SUBMIT VETTING VETTING_CLOSED CLOSED DISPUTED FINAL_TESTING READONLY BETA`

   Set `CLDR_OLDVERSION=1.5.1` to indicate the prior version of CLDR which will be picked up via CVS, in other words, the version which is currently present in common in XML form.

   Set `CLDR_NEWVERSION=1.6` to indicate the new version of CLDR which is being worked on.

3. #### Messages

   Various messages can be shown to users either by configuration parameters, or at run-time for things such as closing for maintanance, announcement of news, etc.

   - `CLDR_HEADER` - this property displays a message at the top of the page without preventing user login. It can be set temporarily in the "Update Special Message" area of the Admin panel.
   - `CLDR_LOCKOUT` - this property locks out all users who do not have the specified passcode. For example, if 'CLDR_LOCKOUT=zanzibar', then users must visit the URL …apps/survey?unlock=zanzibar to log in. This is used for special-purpose testing.

## Procedures

Here are some Survey Tool tasks, with instructions.

- #### Starting the Beta Process

  During the Beta process, users may input any data to test the SurveyTool. At the end of the Beta period, all data is deleted, and reloaded from CVS.

  1. Set a CLDR_HEADER message in the properties file to notify users of the beta period. Also, set the property CLDR_PHASE=BETA
  2. Back up the `cldr/` directory from the server
  3. Log into the SQL console and keep the console open
  4. (Optional: This would be a good time to update from CVS as all data will have to be reloaded)
  5. Restart the server to clear any session data that might be holding the database open
  6. Run the following SQL (remember to check the U/I/D button each time):
     `drop table CLDR_DATA
     drop table CLDR_SRC`
  7. Without browsing to any other areas of the survey tool, Restart the server
  8. Follow the procedure for 'updating from CVS' below.

- #### Ending the Beta Process

  1. NOTE this will remove ALL submitted data and all forum entries.
  2. Log into SQL and execute `drop table cldr_allpaths,cldr_data,cldr_interest,cldr_intgroup,cldr_orgdispute,cldr_output,cldr_result,cldr_src,cldr_status,cldr_vet,cldr_xpaths`
  3. Immediately shut down the Survey Tool and web container
  4. modify cldr.properties so that the CLDR_PHASE option states CLDR_PHASE=SUBMIT - may also wich to modify or comment out CLDR_HEADER
  5. Update the CVS work area (as specified by CLDR_COMMON in cldr.properties) if desired (Survey Tool will start with a clean slate when it starts)
  6. Start up Survey Tool. Follow the procedure from "Updating from CVS" above except that you start with 'Load All Locales'. There's no reason to update Sources, as they will be empty.

- #### Updating from CVS

  1. Run CVS update on the work area (as specified by CLDR_COMMON in cldr.properties).
     Note: If Supplemental data, English, or root was updated, definitely restart the server after the end of this checklist.
  2. Visit the 'Manage Sources' page of the Admin panel
  3. If anything is available to update, click 'Update All'.
  4. Note: if 'root' or 'en' was updated, definitely restart the server after the end of this checklist. Otherwise the cached look for English will be wrong.
  5. Click 'Load All Locales' in the Admin Panel, and click YES. It will take a little while..
  6. (Now, if root, en, or supplemental was updated above, restart the server.)
  7. If there are special bulk votes, or major changes to the data, vetting may need to be recalculated. See next section.

- #### Updating votes

  1. Go to the Admin panel and click Expert-Admin-Only.
  2. Click Update Implied Vetting
  3. Click Update Results Vetting.
     - 'REUpdate All' will recalculate ALL votes. Do this if the voting algorithm changes or if the votes otherwise need to be recalculated.
     - To update just one locale, type its code into the box, click 'Delete before Update', and click Update.
     - Update All will recalculate only missing votes. Should not be needed.
     Note: You can click on 'Stats' or 'Sessions' and reload that page while the 'all' updates occur. It will take a while. A message «SurveyTool may be busy: vetting update in progress» will appear in the header while the update occurs. Wait until it is done before going on to the next step.
  4. Click 'Update Vetting Status' to verify that all votes and locale's status are finished.

- #### Adding Users

  1. Log in to the SurveyTool. To add users for a different organization than your own, you must be logged in as an Admin (level 0) user.
  2. Click the "Manage (Organization) Users" link at the top right of the page.
  3. Note the organization name and spelling of other users listed
  4. Click the "Add User" link at the top left of the page
  5. Fill in fields as follows:

     > Name: User name (can be in their native script, but may want to include Latin transliteration)
     > Email: User's email
     > Organization: Organization or group. Should be spelled as seen on previous page.
     > Userlevel: Set to 1 to create a TC for the specific organization or 5 for a vetter.
     > Locales responsible: Can be left blank for TC. For vetter, should be a list of locales they have write access to.

  6. Click "Add".
  7. SurveyTool will show: user added. Login for user@example.com - this 'Login' link will log you in as that user (and log you out of administration). However, this link can be used for testing or mailed to the user.
  8. SurveyTool will also show: The password wasn't emailed to this user. You can do so in the 'manage users' page.
     Click that 'Manage users' link.
  9. You will be taken to the 'zoomed-in' view for the new user. You can use the 'Action' popup menu to change email or name, or delete the user.
  10. Use the Action popup menu to select 'Send Password'. Click Do Action.
  11. The email will be sent. You can click Add User to add another user.

- #### Sending password resets, modifying email addresses, names or levels

  1. Log in to the SurveyTool. To modify users for a different organization than your own, you must be logged in as an Admin (level 0) user.
  2. Click the "Manage (Organization) Users" link at the top right of the page.
  3. Search in page for the user
  4. Click on the magnifying glass at the left to zoom in on one user.
     (Note: You can operate on multiple users at once with the 'action' popup menu. If you are just working with one, though, it is better to use the zoomed-in view.)
  5. You will be taken to the 'zoomed-in' view for the new user. You can use the 'Action' popup menu to change email or name, or delete the user.
  6. Use the Action popup menu to select 'Send Password'. Click Do Action.
  7. The email will be sent. You can click the "< Show all users" link at the top of the page to work with another user.

## SQL Tasks

Some tasks do not have a nice UI yet, however, they can be accomplished through the SQL Console.

- #### Changing a user's organization

  1. Find the user's details:
     `select * from cldr_users where name like '%Jones%'`
  2. Ensure that you have the spelling of the new organization correct:
     `select distinct org from cldr_users where org like '%United Vetters%'`
  3. Update the user. You can restrict the setting by name or email address, just to make sure you did not have a typo in the ID.
     `update cldr_users set org='United Vetters' where id=731 and name='Vet R. Jones'`
     (Remember to check the U/I/D button, as this is an Update.)
  4. Verify the change:
     `select * from cldr_users where name like '%Jones%'`

## End.