Matching workouts to recorded activities

What "matching" means

A planned workout lives on the calendar. A recorded activity is what the athlete actually uploaded (a FIT, TCX, or GPX file). Matching ties the two together so you get the full comparison: plan-vs-actual, the compliance colour on the calendar pill, the Session analysis and the Similar sessions trend on the workout detail page. (An unmatched upload still shows its own activity analysis — matching adds the vs-plan layer.)

How auto-match works

When an athlete uploads an Activity, Grepiac runs the auto-matcher:

1. Look for planned workouts on the same date with the same sport.
2. Skip workouts already matched, or with match_locked set (user explicitly decided).
3. If multiple candidates exist, pick the one with the closest planned duration to the activity's actual duration.
4. Attach the activity, set status to completed.

The auto-matcher never overrides a manual decision and never matches across dates.

When auto-match gets it wrong

Common failure cases:

• The athlete did two runs on the same day. One was the planned one, the other was a recovery run. The auto-matcher picked the closer duration; if it picked wrong, manually unmatch and re-match.
• The athlete did the prescribed run a day late. The Grepiac will not auto-match across dates. Drag the planned workout to the correct date, then re-upload (or manually match).
• An athlete uploaded the wrong file. The match is bound to whatever file was uploaded. If the file is wrong, unmatch and re-upload the right one.

Manual match / unmatch

From the workout detail page (/athlete/<pid>/workout/<id>/):

• Unmatch: click the "Unmatch" button under the matched activity. This clears the link and locks the workout so auto-match will not re-attach a fresh activity. Status reverts to planned.
• Match to a specific activity: attach a planned workout to a chosen upload — drag the planned workout onto the activity on the calendar, or use the match control. This locks the pairing so auto-match leaves it alone.

What "match locked" means

When you manually match or unmatch, the workout gets match_locked=True. This tells the auto-matcher to leave it alone. If you later want auto-match to consider it again, edit the workout from admin and clear the flag.

Why no cross-date auto-match

The system deliberately does not match a Tuesday Activity to a Wednesday planned workout. The risks (matching the wrong day, getting taper or recovery decisions wrong) are larger than the convenience. The fix is to drag the planned workout to the correct date first.

See also: Calendar overview, Drag and drop in the calendar, Workout notes (three kinds).