Skip to main content

Over-Budget Locking & Documentation

The over-budget system protects against runaway scope by locking tickets when time used exceeds budget thresholds. Additionally, some organizations require documentation before tickets can be closed.

Over-Budget Locking​

How It Works​

When Harvest time entries sync to a ticket, the system calculates budget utilization:

Utilization = Hours Used / Budget Hours

If Utilization > Threshold → LOCK the ticket

A locked ticket cannot receive staff responses until a Project Manager (PM) unlocks it.

Tiered Thresholds​

The system uses tiered multipliers based on budget size:

Budget RangeLock ThresholdExample
0–5 hours150% (1.5×)5h budget → locks at 7.5h used
5–20 hours125% (1.25×)10h budget → locks at 12.5h used
20–50 hours115% (1.15×)30h budget → locks at 34.5h used
50+ hours110% (1.1×)100h budget → locks at 110h used

Smaller budgets get more leeway (150%) since small overruns are expected. Larger projects are held tighter (110%) since even small percentage overruns represent significant hours.

What Happens When a Ticket is Locked​

For the Agent​

  1. A red "OVER BUDGET — LOCKED" badge appears on the ticket
  2. The response form is disabled (cannot post public responses)
  3. Internal notes can still be posted (to communicate with team)
  4. A message indicates who can unlock: "Contact your PM to unlock"
  5. The notification system alerts the assigned PM

For the PM​

  1. Receives notification: "Budget lock triggered on #XXXXXX"
  2. Appears in PM Dashboard → Budget Alerts widget
  3. PM reviews the situation and decides:
    • Unlock — approve additional work (client agreed to more hours)
    • Close — work complete, close the ticket
    • Discuss — add a note and discuss with the agent

Unlocking a Ticket​

PM Unlock Process​

  1. PM opens the locked ticket
  2. Reviews:
    • Budget hours vs. hours used
    • Remaining work needed
    • Client communication about additional hours
  3. Clicks Unlock Ticket
  4. Optionally adds a note (e.g., "Client approved 5 additional hours")
  5. Agent can now respond again

Audit Trail​

Every lock and unlock event is recorded in ost_ticket_over_budget_lock:

FieldDescription
ticket_idThe affected ticket
actionlocked or unlocked
triggered_bySystem (auto-lock) or staff ID (unlock)
budget_hoursBudget at time of event
hours_usedHours used at time of event
notesOptional note from PM
created_atEvent timestamp

Documentation-Required Closing​

Overview​

Some client organizations have a flag requiring documentation before tickets can be closed. This ensures all work is properly documented for future reference.

How It Works​

  1. An organization has the Documentation Required flag set
  2. Agent clicks Close on a ticket from that organization
  3. Instead of closing, status changes to Close Pending
  4. PM receives notification: "Documentation review needed for #XXXXXX"
  5. PM reviews the ticket and documentation
  6. PM clicks Acknowledge Documentation
  7. Ticket moves to Closed status

For the Agent​

When closing a doc-required ticket:

  • Ensure your responses include clear documentation of:
    • What the issue was
    • What was done to resolve it
    • Any configuration changes made
    • Steps for the client to verify
  • After clicking Close, the ticket goes to "Close Pending" (not Closed)
  • Wait for PM acknowledgment

For the PM​

  1. Doc-review tickets appear in PM Dashboard → Documentation Review widget
  2. Open the ticket and review:
    • Is the resolution clearly documented?
    • Could another developer understand what was done?
    • Are there any follow-up items?
  3. If documentation is adequate: Click Acknowledge Documentation
  4. If more documentation needed: Add a note to the agent

Auto-Close Skip​

If a ticket would normally be auto-closed (client inactivity) but has the documentation-required flag:

  • Auto-close is skipped
  • Ticket remains open
  • Tracked in ost_ticket_docs_autoclose_skip
  • Reported in the daily docs digest (cron-docs-digest.php, 7:30 AM CST)

Client-Closed Tickets (Doc Required)​

When a client closes a doc-required ticket:

  1. Ticket status changes to indicate client closure
  2. Recorded in ost_ticket_client_closed_docs_pending
  3. PM receives notification for review
  4. PM can either:
    • Acknowledge and finalize the close
    • Reopen for additional documentation

This prevents clients from bypassing the documentation requirement.

Viewing Budget Status​

On Individual Tickets​

The ticket sidebar shows:

  • Budget Hours / Hours Used / Utilization %
  • Lock status (if locked)
  • Lock/unlock history

On PM Dashboard​

The PM Dashboard (scp/pm.php) has a Budget Alerts widget showing:

  • All tickets approaching budget (75%+)
  • All locked tickets awaiting unlock
  • Quick-action buttons for unlock

Best Practices​

For Agents​

  1. Monitor your utilization — check the sidebar before logging significant time
  2. Communicate early — if you see you'll go over, note it before the lock triggers
  3. Log accurate time — precise Harvest entries help budget planning
  4. Document as you go — don't wait until close to write documentation
  5. Use internal notes — if locked, use notes to explain the situation to your PM

For PMs​

  1. Set realistic budgets — account for standard overhead (communication, testing)
  2. Review alerts promptly — locked tickets block work progress
  3. Communicate with clients — before unlocking, confirm client approves additional hours
  4. Use the dashboard — check Budget Alerts daily
  5. Acknowledge docs quickly — Close Pending tickets are waiting on you

Troubleshooting​

IssueSolution
Ticket locked but hours seem correctCheck Harvest sync is accurate; time zone differences may affect totals
Can't unlock (not a PM)Only staff in PMS_REAL_LIST can unlock — contact a PM
Doc review notification not receivedCheck PM notification preferences
Auto-close happened despite doc-requiredVerify the org flag is set correctly; check autoclose skip tracking
Budget shows wrong hoursCheck Harvest Project ID field links to correct project