mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-19 12:50:11 -05:00
Dries Peeters
12d79816d0
Import window and web activity from a local ActivityWatch aw-server (https://activitywatch.net/) as automatic time entries (source='auto'). - Add ActivityWatchConnector: test_connection, sync_data, get_config_schema - Per-user integration; config: server_url, default_project_id, lookback_days, optional bucket_ids (default: aw-watcher-window_* and aw-watcher-web_*) - No OAuth; setup at /integrations/activitywatch/setup - Idempotent sync via IntegrationExternalEventLink and external_uid - Register connector; treat activitywatch as per-user in IntegrationService - activitywatch_setup route and template; connect redirect and is_global updates - View/manage: Configure and Edit Configuration links for activitywatch - docs/integrations/ACTIVITYWATCH.md; tests for connector and idempotency
61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
# ActivityWatch Integration
|
||
|
||
TimeTracker can import window and web activity from [ActivityWatch](https://activitywatch.net/) as automatic time entries (`source='auto'`). ActivityWatch is an open-source, local-first automated time tracker that runs on your machine.
|
||
|
||
## How It Works
|
||
|
||
- **aw-server**: ActivityWatch’s local server (default: `http://localhost:5600`) stores events from watchers.
|
||
- **Watchers**: e.g. **aw-watcher-window** (active window) and **aw-watcher-web** (browser tabs) write events into buckets.
|
||
- **TimeTracker**: The integration reads from the aw-server REST API and creates `TimeEntry` records with `source='auto'`.
|
||
|
||
One integration is configured **per user**; `server_url` in the integration config points to that user’s aw-server.
|
||
|
||
## Requirements
|
||
|
||
1. **ActivityWatch installed and running**
|
||
- aw-server must be running (typically on port 5600).
|
||
- See: https://activitywatch.net/docs/install/
|
||
|
||
2. **Reachability**
|
||
- The TimeTracker server must be able to reach the aw-server URL (e.g. `http://localhost:5600` if on the same machine, or `http://hostname:5600` on the same network).
|
||
- aw-server usually listens on localhost only; for a remote TimeTracker, the machine running ActivityWatch must expose the port (e.g. `--host 0.0.0.0`) and you accept the network/security implications.
|
||
|
||
## Setup
|
||
|
||
1. In TimeTracker: **Integrations** → **ActivityWatch** → **Connect** (or **Setup**).
|
||
2. Set **ActivityWatch Server URL** (e.g. `http://localhost:5600`).
|
||
3. Optionally: **Default Project**, **Lookback days** (1–90), **Bucket IDs** (or leave empty to use all window and web buckets).
|
||
4. Save; the connection is tested and the integration is marked active on success.
|
||
|
||
## Buckets
|
||
|
||
By default the integration uses buckets whose IDs start with:
|
||
|
||
- `aw-watcher-window_`
|
||
- `aw-watcher-web_`
|
||
|
||
You can override this by setting **Bucket IDs** (comma-separated or JSON array). If none of the given IDs exist, the integration reports an error and lists some of the available bucket IDs.
|
||
|
||
## Sync
|
||
|
||
- **Manual**: Use **Sync Now** on the integration’s detail page.
|
||
- **Automatic**: Enable **Auto sync** and choose **Sync schedule** (e.g. hourly, daily) in the setup.
|
||
|
||
On each sync, the integration fetches events in the configured time range from the selected buckets and creates `TimeEntry` rows. Already-imported events are skipped using `IntegrationExternalEventLink` and an `external_uid` derived from bucket, timestamp, duration, and a hash of the event data.
|
||
|
||
## Imported Data
|
||
|
||
| ActivityWatch | TimeEntry |
|
||
|-------------------------|-----------------------------------|
|
||
| `timestamp` (UTC) | `start_time` (app-local) |
|
||
| `timestamp + duration` | `end_time` |
|
||
| `duration` (seconds) | `duration_seconds` |
|
||
| `data.app` / `data.title` or `data.url` / `data.title` | `notes` |
|
||
| — | `source='auto'` |
|
||
| Config `default_project_id` | `project_id` (or `None`) |
|
||
|
||
## Deployment Notes
|
||
|
||
- **Same machine**: Use `http://localhost:5600`; no extra network setup.
|
||
- **Central TimeTracker, user machines run ActivityWatch**: Each user sets `server_url` to their machine (e.g. `http://user-pc:5600`). aw-server must listen on a reachable interface and the network path must allow it; this is off by default for security.
|