---
title: "Timesheet reference"
description: "The permissions, week states, timer warnings, messages, and MCP tools for timesheets, in tables to look things up in."
url: "https://support.outpostplatform.com/msp/timesheet-reference/"
product: "depot"
type: "reference"
status: "draft"
ai_summary: "MSP timesheets reference. Permissions ticket:write, timesheet:approve (Owner, Support Manager, Project manager), psa:admin. States Draft, Submitted, Approved, Returned. Timer warnings, refusal messages, and the MCP tools get_timesheet_week, add_timesheet_entry, submit_timesheet, review_timesheets, start_timer, stop_timer, list_time_categories."
availability:
  plans: ["msp"]
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/msp/timesheet-reference.md"
license: "CC BY 4.0"
---

# Timesheet reference

This page lists what you look up about timesheets: who can do what, what each
state allows, and what each message means. For how timesheets work, see
[Timesheets](/msp/timesheets/).

## Permissions

| Permission | What it allows | Built-in roles that hold it |
| --- | --- | --- |
| `ticket:write` | Have a timesheet: see **Timesheets** > **My timesheet**, log and change your own time, submit and recall your own week, and use the timer. | Owner, Support Manager, Field Technician, Support Rep, Project manager |
| `timesheet:approve` | Open any technician's week, add other time to it and edit or delete their entries, and approve, return, and reopen weeks. Opens **Timesheets** > **Approvals**. | Owner, Support Manager, Project manager |
| `psa:admin` | Manage time categories and daily targets in **Timesheets** > **Settings**. | Owner |
| `project:time` | Start the timer on a project task, and log time on tasks. | Owner, Support Manager, Field Technician, Project manager |

The **Timesheets** section of the navigation needs `ticket:write`. A custom
role with `timesheet:approve` and no `ticket:write` does not see it.

See [Permissions](/reference/permissions/) and
[Roles and permissions](/depot/roles-and-permissions/).

## Week states

| State | Chip | Time in the week | Who can move it, and to what |
| --- | --- | --- | --- |
| **Draft** | Neutral | Editable | The technician: **Submit week** to **Submitted** |
| **Submitted** | Info | Editable | The technician: **Recall** to **Draft**. An approver: **Approve** to **Approved**, or **Return** to **Returned** |
| **Approved** | Success | Locked on every client | An approver: **Reopen** to **Returned** |
| **Returned** | Warning | Editable | The technician: **Submit week** to **Submitted** |

A week nobody has touched is **Draft**. A week that has not started cannot be
submitted. **Return** needs a note and **Reopen** needs a reason, each up to
1,000 characters. One bulk approve or return takes up to 200 weeks.

## Day strip markers

| Marker | Meaning |
| --- | --- |
| **6:30 / 8:00** | The day's total against its target. A day with no target shows the total only. |
| **Vacation scheduled**, **Sick leave scheduled**, **Holiday**, **Time off scheduled** | Time off booked on the dispatch calendar. Display only; it adds no time. |

## Timer warnings

| Warning | When it shows |
| --- | --- |
| **Running since yesterday** | The timer started before midnight today, in your browser's time zone. |
| **Over 10 hours** | The timer has run for more than 10 hours. |

## Messages

| Message | Cause |
| --- | --- |
| **This week's timesheet is approved. Ask a manager to reopen it.** | The time belongs to a technician whose week is approved. It cannot be added, changed, deleted, or logged from a timer until an approver reopens the week. |
| **The time on this sheet changed after it was opened. Check the new totals and approve again.** | The week's total is not the total the approver saw. Reload it and approve again. |
| **Some client data couldn't be reached. Try again shortly.** | A client's data did not answer, so the week's total is not known. Approval waits until every client answers. |
| **This sheet has moved on since it was opened. Refresh to see where it stands.** | The week is not in a state that allows the action, for example it was recalled or decided by someone else. |
| **That week hasn't started yet, so it can't be submitted.** | You tried to submit a future week. |
| **Another timer is already running. Stop it first, or use Switch timer here.** | You have a timer running on other work. |
| **Last week isn't submitted** | Your previous week is still **Draft** or **Returned**. |
| **1 of 12 clients did not answer**, with the counts for your practice | Time for the clients named under it is missing from the totals on the page. |

## MCP tools

A connected AI app can work with timesheets through these tools, on the MSP
plan only. Each one checks the same permission as the console. See
[Connect AI tools with MCP](/pioneer-ai/mcp-server/).

| Tool | What it does | Risk tier |
| --- | --- | --- |
| `get_timesheet_week` | Reads one technician's week across every client, with its state and totals. Defaults to you and to this week. Another technician's week needs `timesheet:approve`. | Read |
| `add_timesheet_entry` | Logs other time against a time category on one date. Logging for someone else needs `timesheet:approve`. Ticket time is logged with `log_time`. | Write |
| `submit_timesheet` | Submits your week for approval. | Write |
| `review_timesheets` | Approves or returns submitted weeks. Approving needs each week's total exactly as read with `get_timesheet_week`. Returning needs a note. | High, so it needs your approval for every call |
| `start_timer` | Starts your timer on one ticket, project task, or time category. | Write |
| `stop_timer` | Stops your timer and logs it. The minutes default to the elapsed time, and the entry is billable unless the call says otherwise. | Write |
| `list_time_categories` | Lists the time categories, each work or leave. | Read |

There is no tool to reopen an approved week. Reopen it in the console.