This user guide describes how to seamlessly integrate the Roster Athletics platform with the TimeTronics MacFinish timing system.


This guide is divided into a few sections below:



What do you need to do to set up the integration?

  • You have already created the competition on the Roster Athletics platform.
  • You have downloaded and installed the Roster/timing data transfer program named Roster Athletics Agent (you can download the program here: Download and install the RosterAgent).
  • You have a full licence to use the TimeTronics MacFinish software (note that TimeTronics only works with Windows). You can download it here: https://www.timetronics.be/support

 

The RosterAgent program is a small program that allows communications between the Roster platform and TimeTronics so that they can stay in sync with each other during the competition for start lists upload from Roster to TimeTronics and results download and sync from TimeTronics to the Roster platform (and immediately in the app).

 

Now you should have everything ready to start the integration. Make sure you have the following three programs open: 

  1. Roster Athletics in a browser
  2. TimeTronics MacFinish running
  3. RosterAgent running

 


Integration type


The RosterAgent shares information between TimeTronics and Roster using shared PAR files (start lists) and TXT files (results). It works if you are using the same computer or a shared file folder between computers (e.g. one computer running Roster/Roster Agent and another running TimeTronics).


To start integration, you must select the Input directory (start list updates) for PAR files and the Output directory (result files) for TXT files.


TIP: the input and output directories should be folders or sub-folders on a drive (e.g., C:), and you should avoid adding the folder directly to your desktop. 




Starting integration


Prepare for integration


First, enable integration in the Timing system integration section of the competition's Details, by selecting Enabled under TimeTronics export. Enabling the integration reveals additional options.



Start by selecting the Export language. By default, this is set automatically based on the competition country, but you can change it manually by choosing a different language from the list. This language is used to display the event description in TimeTronics and to format the PAR file name using the event description format described below.


In the Exported participants field, choose which participants to export from Roster Athletics to TimeTronics. You can export all participants, or exclude those with DNS and SCR statuses (e.g., when you know an athlete will not attend but do not want to remove them from the list).


In the Exported events field, choose which events to send to TimeTronics. You can export all events or exclude finished events.


Further down in the same section, choose the format to use for PAR files.


There are three Event description format types to choose from. The PAR file name will be displayed as follows:

  • Detailed format: event time, event name, gender (if more than one gender), age group (if more than one age group), event title (if a title is assigned), group/heat number (if they have been assigned).
  • Simple format: event name, gender (if more than one gender), age group (if more than one age group), group/heat number (if they have been assigned).
  • Custom format: lets you choose your file format.



The Custom format field lets you choose the file format. Click on the descriptors of your choice to add them to the field. Erase by simply deleting them. Please note that the field format requires colons around each descriptor, and a single space between descriptors. Thus :EventName: :Gender: would display only the event names and gender for each event. The options are as follows:

  • Age group: always display the event age group
  • Age group opt.: display the event age group if there is more than one age group in the competition (Note: recommend choosing either Age group or Age group opt., but not both)
  • Combined prefix opt.: display the combined parent event if a combined event is used
  • Date: always display the event date in YYYYMMDD format
  • Event label opt.: display the event title if one exists for the event
  • Event name: always display the event name
  • Gender: always display the event's gender
  • Gender opt.: display the event gender only if there is more than one gender in the competition (Note: recommend choosing either Gender or Gender opt., but not both).
  • Group opt.: display the group/heat number only if they are used for the event
  • Stage: always display the event stage
  • Time: always display the event time


If you need to reset the Custom setting, press the Default symbol to restore the initial set of recommended parameters.



Download the authentication file


Open the relevant competition and go to Details. On the left-hand side, click the Agent config button and select TimeTronics (MacFinish).



This will download an authentication .roster file for your specific competition that lets the RosterAgent know to use this competition to connect with TimeTronics MacFinish. Save the file in a place where you can easily find it again. 


Please note: You must use the LAST downloaded authentication file to load into the RosterAgent. Otherwise, the permissions will not match, and you cannot connect to your competition (“Can’t connect - permission denied”).

 


Load the authentication file in the Roster Agent


Once the authentication file is downloaded, go to the RosterAgent. Click on Load configuration and select the latest .roster file (e.g., meeting-xxx-auth.roster) for this competition that you downloaded (as soon as you load the configuration, a ".roster" file will be saved. This file stores the directory information so you don't need to enter directory settings every time.).


Click Start. TimeTronics MacFinish and Roster Athletics are connected if the Result monitor status is Active and the Connection status is Connected.


Stop will stop the connection, and Quit will exit the program completely. To change a configuration file or input/output directories, the connection must be stopped (i.e. no active connection).


 

If you have Show notifications enabled by default, you will see status messages such as:



You can disable notifications by pressing the Show notifications button; it will then appear as a lighter-shaded button.


When the Roster Agent is running, pay attention to the Result monitor and Connection statuses:


Result monitor:

  • Active - normal operational mode
  • Idle
  • Initialising
  • Stopping


Connection:

  • Connecting
  • Connected - normal operational mode
  • Disconnecting
  • Disconnected
  • Reconnecting - the agent will automatically attempt to reconnect
  • Invalid - using the outdated configuration file: try to re-download and then reload the config file



Load events in TimeTronics


Once you have prepared your start lists in Roster Athletics, go to TimeTronics MacFinish. Click on Document in the menu, and select Import Competitors from File...


Select the desired PAR-file (.par). Each start list has a unique PAR-file. You can identify the correct file via the name, which has the following information: "meeting ID - event details with data that you can select in the Event description format - [event ID]" (e.g., [meet1023] 1000 100m - Senior - Heat 1 [10012].par).


 

The ID column in TimeTronics MacFinish will contain information about the bib number and lane/order.


Now the start lists for a particular event are loaded into TimeTronics MacFinish. TimeTronics is now ready to go, and the event can commence in the standard TimeTronics procedure. Once the event has finished and TimeTronics has marked the results, click on Document → Export Results to File.... You can go ahead and use the default event filename when saving. After saving, wait approximately 10 seconds or less while the data is synced to Roster Athletics.



You can now go back to Roster Athletics and see the times and rankings for the athletes that have been updated from TimeTronics. The results are also immediately available in the Roster Athletics App.


Important note: Every time an update to the start list is made in Roster Athletics, it is automatically pushed to the Roster Athletics Agent, but you will still need to open the latest generated PAR-file in TimeTronics MacFinish to load these changes. Also, please note that field events are not supported.


If a wind reading is available in TimeTronics, this information will be automatically transferred to Roster Athletics. 


BIB-numbers: If you have added BIB-numbers in Roster Athletics, they will be under the field Information. 


Competitor status: in TimeTronics MacFinish, the status for each athlete can be set under Time → `click CTRL` + click with the mouse → Status. These status options translate to Roster in the following manner:

  • A time is added and no status → OK + result
  • DNF → DNF
  • DNS → DNS
  • DIS → DQ (+ selection of DQ rule)
  • NR → OK + place, but no result


DQ rules can be added in Roster, but not directly from TimeTronics.


Precision: We recommend using Thousandths as the result precision in TimeTronics. By setting to thousandths, all results will be sent to the Roster system with 1/1000 precision, allowing Roster to assign the correct places automatically. When setting to thousandths, the Roster app and .pdf results printouts will still show hundredths except for when there is a tie in the hundredths place, in which case the thousands place will be used to calculate place and shown accordingly, for example, when two athletes from two different heats have the same result. To set the default precision in TimeTronics MacFinish, click on File → Preferences... → General and mark Precision Linked.



Troubleshooting Tips & Tricks


  • Make sure you are running the latest version of RosterAgent (see Download and install RosterAgent for the latest version number).
  • If a message that says "Can't connect - permission denied" appears when trying to connect to the RosterAgent, make sure you have loaded the latest version of the competition agent configuration file. This file is downloaded from the competition Details → Agent config.
  • The Roster Agent can queue saved TimeTronics results if you lose connectivity (e.g., bad or very slow internet). If you lose the connection, the saved TXT files will be queued and automatically uploaded once the Agent detects it and re-establishes the connection. The upload queue is visible in the RosterAgent and will normally be empty when there are no connection issues, or it will be cleared once any queued results are automatically uploaded.