Tempo Timesheet Management

Logging time is a two-system job: create the worklog through the Jira REST API, then set the Tempo Schedule (work attribute) through the Tempo Cloud API. The Tempo plugin uses the standard Jira worklog endpoint (NOT /rest/tempo-timesheets/), but the Schedule attribute lives only in Tempo's own database and must be set via api.tempo.io.

Setup

1. Copy .env.example to ~/.claude-skills/.env and fill in all variables.
2. JIRA_EMAIL + JIRA_API_TOKEN: from https://id.atlassian.com/manage-profile/security/api-tokens
3. TEMPO_API_TOKEN: from Tempo Settings > API Integration (this is a separate token from Jira — the Jira token returns 401 on api.tempo.io).
4. JIRA_ACCOUNT_ID: your Atlassian account ID (find it in Jira user profile API responses).

Helper Scripts

This skill uses both helper scripts:

# Jira worklogs (Basic auth)
.claude/skills/jira/scripts/jira-api --help

# Tempo API (Bearer token)
.claude/skills/tempo/scripts/tempo-api --help

Workflow

Step 1 — Create the Jira worklog

.claude/skills/jira/scripts/jira-api POST /rest/api/3/issue/{issueKey}/worklog '{
  "timeSpentSeconds": 28800,
  "started": "2026-07-07T09:00:00.000-0400",
  "comment": {
    "type": "doc",
    "version": 1,
    "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Work description here" }] }]
  }
}'

• timeSpentSeconds: hours * 3600 (e.g. 8h = 28800)
• started: use the correct UTC offset for your timezone (e.g. -0400 for EDT)
• Returns 201 with the Jira worklog id
• Batching up to ~10 worklogs in a loop is fine

Step 2 — Resolve the Tempo worklog ID

GET /4/worklogs/jira/{jiraWorklogId} returns 404 on some instances — do NOT rely on it. Instead, after creating all Jira worklogs (wait ~3 seconds for sync), query Tempo's user endpoint:

.claude/skills/tempo/scripts/tempo-api GET '/4/worklogs/user/{accountId}?from=2026-07-07&to=2026-07-07&limit=50'

Match results by startDate + description + timeSpentSeconds to find the tempoWorklogId.

Important: The general GET /4/worklogs?from&to endpoint returns ALL users' worklogs with anonymized descriptions. Always use the /user/{accountId} variant.

Step 3 — Set the Schedule (work attribute)

.claude/skills/tempo/scripts/tempo-api PUT /4/worklogs/{tempoWorklogId} '{
  "issueId": 12345,
  "timeSpentSeconds": 28800,
  "startDate": "2026-07-07",
  "startTime": "09:00:00",
  "description": "Work description here",
  "authorAccountId": "712020:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "attributes": [{ "key": "_Overtime_", "value": "UUID-from-table-below" }]
}'

You must pass the FULL worklog body (issueId, timeSpentSeconds, startDate, startTime, description, authorAccountId) — Tempo overwrites missing fields.

_Overtime_ is Tempo's internal name for the Schedule field. UUID map:

Verify with a follow-up GET:

.claude/skills/tempo/scripts/tempo-api GET /4/worklogs/{tempoWorklogId}

Attributes are at worklog.attributes.values[] (array of {key, value}).

Step 4 — Post-log audit

After all worklogs are posted, re-list the week's worklogs and confirm:

1. Each day totals the expected hours
2. Every worklog has the Schedule attribute set
3. Offer to transition completed tickets (get transition IDs via GET /rest/api/3/issue/{key}/transitions)

Gotchas

• Jira worklog property write is ignored by Tempo: PUT /rest/api/3/issue/{key}/worklog/{id}/properties/tempo succeeds on the Jira side but Tempo ignores it. Always use Step 3 (Tempo PUT endpoint).
• Tempo PUT returns empty body: wrap JSON.parse in try/catch and verify with a follow-up GET.
• Closed timesheet periods return 403 "Period is closed": an admin must reopen the period before backdated worklogs will take.
• Timezone display: Jira ADF started time in -0400 may display shifted in Tempo (UTC-6 board display); harmless for daily totals.

Listing Existing Worklogs

# Get a user's worklogs for a date range
.claude/skills/tempo/scripts/tempo-api GET '/4/worklogs/user/{accountId}?from=2026-07-01&to=2026-07-07&limit=50'

# Get worklogs for a specific Jira issue
.claude/skills/tempo/scripts/tempo-api GET '/4/worklogs/issue/{issueId}?from=2026-07-01&to=2026-07-07'

Deleting a Worklog

Delete from Tempo (which cascades to Jira):

.claude/skills/tempo/scripts/tempo-api DELETE /4/worklogs/{tempoWorklogId}