# Benutzerhandbuch ## Notion → Apple Kalender / Exchange Sync Willkommen! Dieses Tool nimmt deine in Notion abgeschlossenen Aufgaben und legt für dich automatisch saubere Kalendertermine im Apple Kalender an — die dann via Exchange in Outlook landen. So musst du am Monatsende nicht mehr manuell Termine nachpflegen. --- ## Inhaltsverzeichnis 1. [Was macht das Tool?](#1-was-macht-das-tool) 2. [Voraussetzungen](#2-voraussetzungen) 3. [Einmalige Einrichtung](#3-einmalige-einrichtung) 4. [Tägliche / monatliche Nutzung](#4-tägliche--monatliche-nutzung) 5. [Was passiert bei mehrfacher Ausführung?](#5-was-passiert-bei-mehrfacher-ausführung) 6. [Termin nachträglich korrigieren](#6-termin-nachträglich-korrigieren) 7. [Häufige Fehler & Lösungen](#7-häufige-fehler--lösungen) 8. [FAQ](#8-faq) --- ## 1. Was macht das Tool? Das Skript liest Aufgaben aus deiner Notion-Tasks-Datenbank, die - den **Status `Done`** haben **und** - ein **Erledigt-Datum** in einem bestimmten Monat tragen. Pro Tag und Projekt entsteht **mindestens ein** Kalendertermin. Er enthält: - **Titel:** alle erledigten Aufgaben dieses Tages für dieses Projekt, mit Semikolon getrennt. - **Beschreibung:** der Projekt-Anzeige-Name (z. B. ein Projekt-Code). - **Dauer:** Summe aller T-Shirt-Größen der enthaltenen Aufgaben (XS = 15 min, S = 30, M = 60, L = 120, XL = 240). - **Startzeit:** Der erste Termin eines Tages startet um 09:00 (konfigurierbar). Folgetermine schließen nahtlos an. > **Outlook-Titel-Limit:** Outlook schneidet Terminbezeichnungen bei 248 Zeichen ab. Würde der zusammengesetzte Titel eines Projekts diese Grenze überschreiten, legt das Skript automatisch mehrere aufeinanderfolgende Termine an – jeder mit einer Teilmenge der Aufgaben, die ins Limit passt. Im `--dry-run`-Modus wird trotzdem nur **eine Zeile pro Projekt und Tag** angezeigt (Gesamtdauer und Gesamtzeitraum), damit die Übersicht erhalten bleibt. **Beispiel:** | Notion-Aufgabe | Datum | Projekt | Größe | |----------------------|------------|-----------|-------| | Konzept erstellt | 03.04.2026 | EfA-RI-NI | M | | Review-Meeting vorb. | 03.04.2026 | EfA-RI-NI | S | | Statusbericht | 03.04.2026 | DiPlanung | XS | Wird zu: | Termin | Datum | Titel | Beschreibung | |----------|-------------|---------------------------------------------|--------------| | 09:00–09:15 | 03.04.2026 | Statusbericht | DiPlanung | | 09:15–10:45 | 03.04.2026 | Konzept erstellt;\nReview-Meeting vorb. | EfA-RI-NI | Die Reihenfolge pro Tag ist alphabetisch nach Projektname — bei Re-Runs identisch und damit reproduzierbar. ## 2. Voraussetzungen - **Mac mit macOS** (das Tool nutzt AppleScript). - **Apple Kalender App**, verbunden mit deinem Exchange-/Outlook-Account. - **Python 3.8 oder neuer**, plus die Pakete `requests` und `python-dateutil`. - **Notion-Account** mit: - einer **Tasks-Datenbank** (mit Properties wie `Status`, `Completed on`, `T-Shirt Size`, `Project`), - einer **Projects-Datenbank**, auf die `Project` als Relation zeigt, - einer **Internal Integration** mit Zugriff auf **beide** Datenbanken. ## 3. Einmalige Einrichtung ### 3.1 Python-Pakete installieren Im Terminal: ```bash pip3 install requests python-dateutil ``` ### 3.2 Notion-Integration erstellen 1. Öffne . 2. *„+ New integration"* → Name vergeben (z. B. „Calendar Sync") → Workspace wählen. 3. Nach dem Erstellen siehst du den **„Internal Integration Token"** (beginnt mit `secret_`). Kopieren — den brauchst du gleich. ### 3.3 **Wichtig:** Beide Datenbanken mit der Integration teilen > Das ist die häufigste Fehlerquelle. Wenn du das überspringst, „verschwindet" die `Project`-Relation aus der API. Für **jede** der beiden Datenbanken (Tasks **und** Projects): 1. Datenbank in Notion öffnen. 2. Oben rechts auf das `…`-Menü → **„Connections"**. 3. Deine Integration auswählen → bestätigen. ### 3.4 Datenbank-ID kopieren 1. **Tasks-Datenbank** in Notion öffnen. 2. URL ansehen: `https://www.notion.so//?v=…` 3. Den 32-stelligen Block vor `?v=` kopieren. Beispiel: `https://www.notion.so/marius/22710a5f51bd81548772dd6626cfdb7f?v=abc` → ID = `22710a5f51bd81548772dd6626cfdb7f`. ### 3.5 Apple Kalender vorbereiten 1. Apple Kalender öffnen (`open -a Calendar`). 2. In der linken Seitenleiste den Kalender finden, der auf das Exchange-Konto zeigt. 3. **Exakten Namen** notieren — Groß-/Kleinschreibung und Leerzeichen zählen (z. B. `TSM`). ### 3.6 `config.json` befüllen Im Projektordner liegt eine `config.json`. Trage deine Werte ein: ```json { "notion_token": "secret_DEIN_TOKEN", "notion_database_id": "DEINE_DATENBANK_ID", "calendar_name": "TSM", "day_start_hour": 9, "t_shirt_size_map": { "XS": 15, "S": 30, "M": 60, "L": 120, "XL": 240 }, "protocol_file": "sync_state.json", "log_file": "notion_sync.log", "notion_property_names": { "name": "Name", "size": "T-Shirt Size", "last_edit": "Completed on", "project": "Project", "status": "Status" }, "projects": { "EfA-RI-NI": "NII001", "DiPlanung": "ITN001" } } ``` **Was bedeutet was?** | Feld | Bedeutung | |------|-----------| | `notion_token` | Dein Internal-Integration-Token aus Schritt 3.2. | | `notion_database_id` | ID der Tasks-Datenbank aus Schritt 3.4. | | `calendar_name` | Name des Exchange-Kalenders aus Schritt 3.5. | | `day_start_hour` | Uhrzeit, ab der der erste Termin des Tages liegt. `9` bedeutet 09:00. | | `t_shirt_size_map` | Wie lang ist eine Aufgabe je T-Shirt-Größe (in Minuten)? | | `protocol_file` / `log_file` | Dateinamen für Status & Log — Default ist meist OK. | | `notion_property_names` | Wenn deine Notion-Properties anders heißen, hier eintragen. | | `projects` | **Filter + Mapping**: Schlüssel = Projektname **wie er in Notion steht**, Wert = wie er **im Kalender** angezeigt wird (Beschreibung). Nur Projekte aus dieser Liste werden synchronisiert. Ist `projects` leer, werden alle Projekte synchronisiert. | ## 4. Tägliche / monatliche Nutzung ### Standard-Aufruf (vergangener Monat) ```bash open -a Calendar python3 notion_to_calendar.py ``` → Synchronisiert automatisch den **vergangenen Monat**. Wenn du im Mai aufrufst, werden also die Aprildaten gezogen. ### Bestimmten Monat angeben ```bash python3 notion_to_calendar.py --monat 2026-04 ``` ### Vorschau (nichts ändern) ```bash python3 notion_to_calendar.py --monat 2026-04 --dry-run ``` → Zeigt eine Tabelle mit allen Terminen, die angelegt/aktualisiert würden, ohne irgendetwas zu schreiben. Oberhalb der Tabelle erscheint eine Legende zur Farbkodierung. **Farbkodierung:** | Spalte | Farbe | Bedeutung | |--------|--------|-----------| | Dauer | grün | Tagessumme ≥ 8 h (≥ 480 min) | | Dauer | rot | Tagessumme > 10 h (> 600 min) | | Datum | orange | Wochensumme > 48 h (> 2880 min) — alle Tage dieser Woche werden markiert | ### Anderen Kalender wählen ```bash python3 notion_to_calendar.py --monat 2026-04 --kalender "Privat" ``` → Überschreibt einmalig den Kalendernamen aus `config.json`. ## 5. Was passiert bei mehrfacher Ausführung? Das Skript ist **idempotent**: - Termine, die unverändert sind, werden **übersprungen** (kein Update). - Termine, die in Notion korrigiert wurden (z. B. T-Shirt-Größe geändert, Aufgabe ergänzt), werden **aktualisiert** — der bestehende Kalendertermin wird überschrieben, **nicht** gelöscht und neu angelegt. Outlook-Empfänger:innen sehen also dieselbe UID. - Nachfolgetermine eines Tages, deren Startzeit sich durch eine Längenänderung verschoben hat, werden **automatisch ebenfalls aktualisiert**. Du kannst das Skript also problemlos mehrfach pro Monat ausführen. ## 6. Termin nachträglich korrigieren 1. Ändere die Aufgabe in Notion (z. B. T-Shirt-Größe). 2. Stelle sicher, dass `Status = Done` und `Completed on` weiterhin gesetzt sind. 3. Skript erneut laufen lassen: ```bash python3 notion_to_calendar.py --monat 2026-04 ``` 4. Im Log siehst du `GEÄNDERT: …` für die betroffenen Termine. ## 7. Häufige Fehler & Lösungen ### „Eigenschaft 'Project' nicht in der Notion-Datenbank gefunden." **Ursache:** Die Projects-Datenbank ist nicht mit deiner Integration geteilt. **Lösung:** Schritt 3.3 wiederholen — Connections auch in der Projects-DB setzen. ### „FEHLER: Ungültiger Notion-Token." **Ursache:** Token in `config.json` falsch oder abgelaufen. **Lösung:** Token unter neu kopieren. ### „FEHLER: Notion-Datenbank nicht gefunden." **Ursache:** Datenbank-ID falsch **oder** Tasks-DB nicht mit der Integration geteilt. **Lösung:** ID kontrollieren, in der Tasks-DB Connections setzen. ### „FEHLER: Kalender 'XYZ' nicht gefunden." **Ursache:** `calendar_name` weicht vom tatsächlichen Namen in Apple Kalender ab. **Lösung:** Namen exakt übernehmen (Groß-/Kleinschreibung, Leerzeichen). ### Apple Kalender fragt nach Berechtigung Beim ersten Lauf erscheint ein macOS-Dialog: „Terminal möchte 'Calendar' steuern". → **Erlauben**. Lässt sich später unter *Systemeinstellungen → Datenschutz & Sicherheit → Automation* anpassen. ### Im Kalender steht alles Mehrfach! **Symptom:** Doppelte oder dreifache Termine an denselben Tagen. **Ursache:** Wahrscheinlich wurde `sync_state.json` gelöscht und das Skript neu gestartet. **Lösung:** Doppelte Termine in Apple Kalender manuell löschen. Ab jetzt `sync_state.json` nicht mehr anfassen. ### „Seite '…' Last Edit fehlt – übersprungen" **Ursache:** Die Notion-Page hat kein Datum in der konfigurierten `last_edit`-Property. **Lösung:** Datum eintragen oder Aufgabe als nicht erledigt belassen. ## 8. FAQ **Welche Notion-Properties brauche ich genau?** Pflicht in der Tasks-DB: - ein Title-Feld (heißt typischerweise `Name` oder `Task Name`), - ein Select-Feld für die T-Shirt-Größe (Werte XS / S / M / L / XL), - ein Datums-, `Last edited time`-, `Created time`- oder Formula-Feld für `Completed on`, - eine Relation auf die Projects-DB, - ein Select- oder Status-Feld `Status` mit dem Wert `Done`. Heißen sie bei dir anders? Dann passe sie in `notion_property_names` an. **Werden auch Aufgaben ohne Größe synchronisiert?** Nein. Ohne T-Shirt-Größe wird die Aufgabe übersprungen und im Log vermerkt. **Werden Aufgaben **aller** Projekte synchronisiert?** Nur die in `projects` aufgelisteten — alles andere wird übersprungen. Wenn du **alle** willst, lass `projects` leer (`{}`) oder lass den Block ganz weg. **Was passiert, wenn ich einen Termin manuell im Kalender lösche?** Beim nächsten Lauf merkt das Skript, dass die UID nicht mehr existiert, und legt den Termin **neu** an. Eine Warnung erscheint im Log. **Kann ich das Tool für mehrere Notion-Datenbanken nutzen?** Aktuell ein Skript = eine `config.json` = eine Tasks-DB. Für eine zweite DB einen separaten Ordner mit eigener `config.json` und eigener `sync_state.json` anlegen. **Wie lange dauert es, bis Outlook die Termine sieht?** Apple Kalender synchronisiert im Hintergrund mit Exchange. Üblich sind 1–5 Minuten. Bei größeren Änderungen kann es länger dauern. **Gibt es einen Zeitplan / Auto-Run?** Nein, der Sync ist bewusst manuell ausgelöst. So behältst du die Kontrolle, wann Termine entstehen. --- Viel Erfolg! Bei Auffälligkeiten lohnt sich immer ein Blick in `notion_sync.log` — dort steht, welche Pages aus welchem Grund übersprungen wurden.