Section 4.2 - Importing preregistration - details
The import module allows for a csv file to be imported into an fsTimer registration database. Starting from an Excel or Libreoffice spreadsheet, you can do "Save as" to save it as a csv file.
See the fstimer_demo_online_registration.csv file that comes in the fstimer_demo project preloaded in fsTimer for an example of how the spreadsheet should be formatted. The first row is a header row, giving the name of each column.
After pressing "Open" and selecting a csv file, the field mapping window will open:
For each registration field (left column), you must specify which CSV column contains data for that field (middle column). CSV fields with names that exactly match registration fields are automatically matched, but can be re-assigned. Clicking on an entry in the middle column will bring up a drop-down list of all of the CSV fields present in the file. If you do not wish to map any of the csv fields to a particular registration field (for instance, maybe you do not have IDs in your csv file) then click on the drop-down menu and select "-- Leave Empty --".
For any registration field, you can also specify to use an "-- Advanced expression --", which allows specifying a custom python expression. If you select this option, then you must fill the expression in the right column. Expressions can combine values from several CSV columns using the "reg" variable to refer to columns. This variable is a dictionary whose keys are the CSV column's name, and who's value will be the data value of that column. For example, if there were a registration field "Name" but the CSV contained columns "First Name" and "Last Name", the following expression could be used to map both of those columns to "Name" in the correct way:
' '.join([reg['First name'], reg['Last name']])
Any python function of the CSV data can thus be used to populate a registration field. If the expression fails to evaluate, it will be noted on the field mapping window. Also, if a registration field has not either been assigned a CSV field or specified to be left empty, then it will be noted on the field mapping window. Otherwise, when you press "OK" on the field mapping window, it will close and the outcome of the importing will be noted on the preregistration screen:
"Found csv fields" lists all of the columns found in the csv file (these will be exactly all of the column headers). "Matched csv fields" lists all of the columns from the csv file that were automatically matched with the registration database fields by having identical names. "Did not match csv fields" lists the columns from the csv file that did not have exact matches in the registration database. "Did not find in csv" lists the registration fields that were not automtically matched with CSV columns - these fields were either manually assigned or specified to be left blank. In this case, "ID" is a registration field but was not in the csv (that will be the case if you assign bib IDs when runners pick up their bibs, as we do).
If you are importing data into a combobox (recall, this is the type of field that must take one of a few values) then all of the entries in that column in the csv file must match exactly one of the combobox values. For example, by default the "Gender" registration field is a combobox that takes values "male", "female", or blank. If "Gender" is matched to a column in the csv file, then all of the values in that column must be either "male", "female", or blank. This is case sensitive - "Male" will not match "male". If you try to import a csv file for which the values in a combobox column do not take valid values, you will get an error:
The error tells you what the invalid value is ("Male" instead of "male", "female", or blank), and where in the csv the error is (row 25). Correct any errors until the csv imports directly. When the csv is successfully imported, it will write the corresponding registration database file to a file named project_name_registration_prereg.json, in the directory fstimer/project_name. The file name is printed in the text field on the pre-registration window. Note that if a file project_name_registration_prereg.json already exists (for instance, because you already imported another csv in this same project), it will be overwritten.
Continue on to Section 4.3 Registration - details.