Skip to main content

Time Tracking & Harvest

Harvest integration provides time tracking, project management, and budget monitoring for tickets. Time entries logged in Harvest are synced to tickets and displayed in the timeline.

Overview​

The Harvest integration connects ticket work to billable time:

Agent works on ticket
  → Logs time in Harvest against the linked project
  → Sync cron imports entries into ticket system
  → Timeline shows interleaved time entries and ticket events
  → Budget utilization calculated and displayed
  → Over-budget triggers lock if threshold exceeded

Viewing Time Data on a Ticket​

FieldDescription
Harvest ProjectLinked Harvest project name (click to open in Harvest)
Budget HoursTotal allocated hours for this work
Quoted HoursHours originally quoted to the client
Hours UsedTotal time entries from Harvest
UtilizationPercentage: Hours Used / Budget Hours

Timeline View​

Navigate to the ticket's Timeline tab (or scp/timeline/):

  • Shows thread entries (messages, responses, notes) interleaved with time entries
  • Time entries show: who logged, hours, date, and notes
  • Entries are ordered chronologically for a complete picture of work
  • Color-coded: thread entries vs. time entries are visually distinct

Logging Time​

From the Ticket Page (Direct Entry)​

New Feature (Alpha)

You can now log time directly to Harvest from the reply and note forms — no need to switch to the Harvest app.

When you open a ticket that has a linked Harvest project, a Log Time to Harvest panel appears at the bottom of both the reply and note forms.

First-Time Setup: Connect Your Harvest Account​

  1. The panel shows a Connect button on first use
  2. Click Connect — a popup opens to Harvest's authorization page
  3. Log in with your Harvest credentials and authorize the ticket system
  4. The popup closes automatically and the panel activates
  5. You can also connect from Profile → Harvest tab

Using the Timer​

  1. Check the Log Time to Harvest checkbox to expand the panel
  2. Click ▶ Start — a running timer begins (synced to Harvest's native timer, persists across tabs/devices)
  3. Work on the ticket and write your reply or note
  4. Click ⏹ Stop — elapsed time displays with a green checkmark
  5. Submit your reply/note — the timer's hours and your notes are pushed to Harvest

Manual Hours​

If you prefer to enter hours manually instead of using the timer:

  1. Check the Log Time to Harvest checkbox
  2. Enter hours in the Hrs field (minimum 0.25, increments of 0.25)
  3. Optionally select a specific task from the dropdown
  4. Submit your reply/note

AI Note Generation​

Click the ✦ (magic wand) button next to the note field to auto-generate a concise description from your reply/note text using AI. The AI summarizes your full message into a 2–8 word Harvest-friendly time entry note.

Tab Switching​

If you start filling in the Harvest panel on the Note tab and then switch to the Reply tab (or vice versa), all Harvest settings — checkbox, hours, timer state, task selection, and notes — transfer automatically to the active tab.

In Harvest Directly​

  1. Open Harvest (web or desktop app)
  2. Select the project linked to the ticket
  3. Log your time with descriptive notes
  4. Entries will sync to the ticket on the next cron run

Project Linking​

Automatic Project Creation​

When certain conditions are met, a Harvest project is automatically created:

  • Ticket reaches a certain status
  • Staff triggers project creation from the ticket
  • Budget hours are assigned

Manual Project Linking​

If a Harvest project already exists:

  1. Open the ticket
  2. Edit the Harvest Project ID custom field
  3. Enter the Harvest project ID
  4. Save — the system will start syncing entries from that project

Budget Monitoring​

Budget Fields​

FieldSet ByDescription
Budget HoursPM or adminTotal hours allocated
Quoted HoursPMHours quoted to client
Hours UsedAutomated (sync)Sum of Harvest time entries

Utilization Display​

The budget utilization percentage is calculated:

Utilization % = (Hours Used / Budget Hours) × 100

Displayed with color coding:

  • 🟢 0–75% — On track
  • 🟡 75–90% — Approaching limit
  • 🟠 90–100% — Near budget
  • 🔴 100%+ — Over budget (locked)

Over-Budget Alerts​

When utilization exceeds the threshold, the system:

  1. Locks the ticket (prevents further responses without PM unlock)
  2. Sends notification to assigned PM
  3. Shows "Over Budget" badge on the ticket

See Over-Budget Locking for the complete workflow.

Sync Schedule​

CronFrequencyWhat
tools/harvest-times-used-import.phpPeriodicImports new time entries, updates budgets

Sync Behavior​

  • Only imports entries newer than the last sync
  • Deduplicates using Harvest entry IDs
  • Updates budget utilization after import
  • Triggers over-budget check for affected tickets

Common Scenarios​

"Where's my time entry?"​

If you logged time in Harvest but don't see it on the ticket:

  1. Wait for the next sync cycle (runs periodically)
  2. Verify you logged against the correct Harvest project
  3. Check the Harvest Project ID field on the ticket matches

"Budget shows 0 hours"​

The PM or admin needs to set the Budget Hours field:

  1. Open the ticket
  2. Edit the Budget Hours custom field
  3. Enter the allocated hours
  4. Save

"Ticket shows wrong project"​

  1. Open the ticket
  2. Check the Harvest Project ID custom field
  3. Correct it to the right project ID
  4. Entries from the wrong project will remain until cleaned up manually

Troubleshooting​

IssueSolution
No time entries showingCheck Harvest project is linked; wait for sync
Budget not calculatedVerify Budget Hours field is set (not 0)
Old entries missingSync only pulls recent entries; historical import needed
Duplicate entriesShould be prevented by UNIQUE key; report to admin
Timeline not loadingCheck JavaScript console; try hard refresh