Unlike most of the other parts of the Resource Area that just need a bit of setup for a new year, score sheet generation is a much longer process.  This is not because the website is particularly cumbersome in this area, it is more because there is a reasonable amount of work (since the challenges change each year) and many parties need to agree.


In this topic we will roll-out the full process that we have been using.


Development of score sheets usually happens on a site that teams and affiliate staff do not have access to.  This allows development to happen before the team challenges are released.  Even after release, it avoids setting incorrect expectations.  Once the process is largely over, the approved score sheet are moved to the live site for all to see.


Step 1: handle the pre-requisites


  • The new program year needs to be set up (part of annual setup).
  • The Challenges needs to be defined (part of annual setup). 
  • You probably want to review with the scoring team if there are any substantial changes to scoring this season that might result in changes to the forms.  These may require code changes.  For example: we introduce percentage deductions on the deduction worksheets in 2013.
  • Get a copy of each team challenge from the Program Directors.  It is helpful to start the score sheet generation before the challenges are released.  This process can flush out some issues in the Scoring Section of each  challenges. 
  • You will need the new logos for this year


Step 2: prep the XML directory


Score sheet generation is in the Resource Area, documents=>create score sheets.  

This step will give you a set of base files to work from for the new season.  

  • go to documents=>score sheets to find the Score Sheet wizard (typically not a public site)
  • pick the New Year Pane
  • set the program year to the latest year
  • click on Prep Year button


The Prep Year button will:

  • create the xml directory for this year if it does not exist 
  • copy and rename all the content files from last year (rename changes the year which is in the file names)
  • copy and rename all the layout files from last year 
  • add all score sheets copied to the table di_scoresheet and mark them as preliminary 


Now the copied files will need to be edited for this year. To test that all this worked successfully, you can go to the Blank Score Sheets pane and try creating an appraiser sheet for a challenge.  It should have the new challenge name, but the scoring elements will be for last year's challenge.

 

Note that Prep Year button can be clicked more than once. Files are only copied if they are not already in this year's xml directory. The di_scoresheet table for this year is re-computed so you will lose the worksheets records, but those can be re-added quickly as explained below.


Step 3: edit the content files

 

Open up each content XML file using a standard code editor (one that understand XML is preferable). Using the Scoring section of the team challenge, start putting together the areas, sections, and items as described in content file details. I find it easiest to cut and paste the actual text of the sections and items directly from the challenge to the content XML file.


There is no formal description of the XML file.  Here are a few notes:

  • kinds of files
    • <letter>_<year>_content.xml are content files (eg a_2024_content.xml)
      • These files define the structure of the score sheet that includes areas, sections, an items.
        Check out the prior year to see how these constructs are used to structure a score sheet.
      • Most of the text on the score sheet is defined in these file.  This includes headings, sections, score items, and definitions.
    • <letter>_tc_appr_layout.xml (eg a_tc_layout.xml)
      • These files position the areas and other constructs (eg appraiser_box) on the page
      • They also define column used on the score sheet
      • All positions are in millimeters (mm) from the upper left corner
      • The default font size is specified as is the increment to the next item (going from A.1 to A.2)
    • <letter>_tc_deduct_layout.xml
      • These files position the areas and other construction on a deduction worksheet
    • <letter>_<year>_ws.xml (eg a_2023_ws.xml)
      • Is the layout for a worksheet
      • If a challenge has a worksheet it will be listed at the end of it's content file
    • *.pdf
      • a pdf to be embedded in a score sheet
    • tc_stick_note_layout
      • is the layout for all sticky notes
      • sticky note sheets include the challenge logo.  The logo images are expected to be in the DMS assets area of the website.
      • the expected file name for a logo is 
        assets/logo/<year>/<letter>_<year>_logo.png  

 

Step 4: edit the layout files

 

Work on a challenge at a time. Step 2 above will produce a starter content file for a challenge. Most years do not change <area>s from the prior year.  You can edit, add, or delete <section>s and <item>s to match this year's challenge.  Most challenges have examples of subjective an objective score items.  You will also see items with and without definitions.  If you are looking for something in particular, see if a prior year challenge might be used as an example.


Once you have the content file edited, try running it by uploading the content file to your server.  


       Documents=>create score sheets Blank Score Sheets red tab


should display your new score sheet if you pick the correct year / challenge / Appraiser Score Sheet.


Two initial problems you might encounter:

  1. 2 score items overlap
    In this case you can adjust the corresponding <letter>_tc_appr_layout.xml.   Look for <part item="area"...> construct for area of interest.  You can adjust where it starts by changing the y="" value.

    If there is just too much text, you can adjust the how close lines are (incr=""near the top of the file) or the fontsize="".
    My suggestion is to try adjusting the incr before the fontsize.

  2. you have too much white space
    This is the inverse problem to #1.  Try increasing the fontsize and the incr value first.  You can also further space the areas.


After each change, regenerate the score sheet to see the effect of your adjustments.

 

Deduction score sheets are adjusted the same way but using the <letter>_tc_deduct_layout.xml.


Step 5: send score sheets for review

 

The Resource Area will generate a zip file with a copy of each sheet that you can email to others to review.  You will find the menu pick at


    1. Documents=>create score sheets; New Year red tab
    2. click the Create All Sheets button

 

Step 6: create initial worksheets

 

Creating worksheets is a bit of an art. Some worksheet such as the one for challenge A have little in common from year to year. The challenge E worksheets are more stable. The check-in worksheet needs to be adjusted with the specifications for this year's structure. These are typical found close to one another within the text of the challenge. The weight held sheet may need adjusting to handle any special bonus for this year's challenge.

 

These score sheet are typically developed in MS Excel and then output as a PDF. The initial copying of files done by Prep Year does not include worksheets. Once you have developed a worksheet, save the PDF to the XML directory. You can likely use last year's layout file for the sheet by copying it and changing the year. Use the controls in Add a new score sheet box of the Prep Year pane to add the worksheet to the table di_scoresheet. Note that worksheets have a subtitle. Where it makes sense, use the same subtitle as last year (eg Structure Check-In or Weight Placcement). The content XML file for the challenge will also need an area for each worksheet. There is probably one already at the end of the file.

 

It appears to be common practice that the score sheet developer or ICM for Scoring makes a first attempt at these worksheets for review and updating by the ICMs. This is actually a good thing in that this person:

  • interacts with the score room to find out what are inputs to the scoring program
  • will likely need to adjust the score sheets for where the results of the worksheets are recorded
  • remembers the desire of the score room to have input fields and only input fields on the very right of the sheet (like other score sheets)


Step 7: going live

 

There are likely multiple ideas of going live: 

  • the new XML directory needs to get checked into SVN (this is the correct way to get the files to the live server)
    • the database on the live server needs updating with new challenges if that has not already been done
    • new score sheets - once checked in and replicated on the live server Prep Year button will update the ev_scoresheet table. You will need to add the worksheets by hand.

 

  • the score sheets need to be transitioned from preliminary to final 
    • you only want to do this when they are final -- the review could go on for a number of weeks
    • making them final or preliminary is accomplished on the New Year pane by clicking on the icon in the final column
      • the red dash is preliminary
      • the green check is final