Actual Budget Smart-Home-Integration, kostenlos und Open Source

Kontostände und Umschläge des Monats deines Actual Budget in Gladys.

• Veröffentlicht von guim31
• Geräte
• Version 1.0.0
• Erfordert Gladys >=5.1.0
• ★ 0

Auf GitHub ansehenAlle Integrationen

Dein Umschlag-Budget in Gladys: die Stände deiner Konten, das noch zu budgetierende Geld und der Stand jedes Umschlags des Monats, gelesen aus deinem eigenen Actual Budget, der freien und selbst gehosteten Budget-App.

Die Integration liest nur: sie schreibt nie in dein Budget und legt keine Buchung an. Die Integration spricht direkt in deinem Netzwerk mit deinem Actual-Server, über das offizielle Paket @actual-app/api. Nicht mit Actual Budget verbunden.

Was du bekommst

• Ein Gerät pro offenem Konto (Girokonto, Sparkonto, Kreditkarte, Depot außerhalb des Budgets…): sein Stand, mit Verlauf.
• Ein Gerät pro Kategorie des Budgets (ein Umschlag): budgetiert, ausgegeben und übrig in diesem Monat, und der verbrauchte Anteil des Umschlags.
• Ein Monatsgerät: zu budgetierendes Geld, diesen Monat ausgegeben und Einnahmen des Monats.
• Ein Dashboard-Widget: das zu budgetierende Geld, die Stände deiner Konten und die Umschläge des Monats.
• Ein Szenen-Auslöser: ein Umschlag erreicht 50, 75, 90 oder 100 % seines Geldes oder ist überzogen.
• Zwei Szenen-Aktionen: Kontostände oder Umschläge lesen, als Satz zum Senden per Nachricht oder zum Vorlesen.

Voraussetzungen

• Gladys Assistant 5.1 oder neuer.
• Ein Actual-Server (actual-server, getestet mit 26.10.0), vom Gladys-Rechner aus erreichbar (gleiches Netz, VPN oder öffentliche Adresse), mit Anmeldung per Passwort.
• Das Passwort des Servers, und das Verschlüsselungspasswort, wenn dein Budget Ende-zu-Ende-verschlüsselt ist.

Konfiguration

Die Sync-ID finden

Hat dein Server nur ein Budget, lass die Sync-ID leer: die Integration nimmt dieses. Sonst öffne in Actual das Budget, dann Einstellungen → Erweiterte Einstellungen anzeigen: dort steht die Sync-ID. Kopiere sie vollständig.

Einstellungen

Einstellung	Wirkung
Adresse des Actual-Servers	Die Adresse, unter der du Actual öffnest, z. B. http://192.168.1.20:5006 oder https://budget.home
Server-Passwort	Das Passwort, mit dem du dich bei Actual anmeldest
Sync-ID des Budgets	Leer für das einzige Budget des Servers, sonst die oben gefundene Sync-ID
Verschlüsselungspasswort	Nur für ein Ende-zu-Ende-verschlüsseltes Budget
Währung	Automatisch (die in Actual eingestellte Standardwährung, sonst Euro), oder Euro, Dollar, Pfund, CHF…
Aktualisierungsintervall	5, 10, 15 (Standard), 30 oder 60 Minuten
Sprache der Texte	Namen der Funktionen (bei ihrer Erstellung) und Sätze der Szenen

Speichere, dann klicke auf Verbindung testen: die Antwort nennt die Zahl der offenen Konten und Kategorien des Budgets oder, bei mehreren Budgets ohne Sync-ID, ihre Namen und Sync-IDs. Öffne dann den Tab Entdecken und füge die gewünschten Geräte zu Gladys hinzu. Nur die hinzugefügten Geräte werden verfolgt: ihre Zustände, das Widget, der Auslöser und die Aktionen betreffen nur sie.

Geräte

Gerät	Funktionen
Konto	Kontostand (negativ bei einer Kreditkarte im Minus)
Kategorie	Budgetiert, Ausgegeben, Verbleibend (negativ wenn überzogen), Umschlag verbraucht (%)
Monat	Zu budgetieren, Diesen Monat ausgegeben, Einnahmen des Monats (alle Einnahmen, Anfangsbestände inklusive)

Beträge in Euro, Dollar oder Pfund zeigen ihre Einheit; eine andere Währung wird an den Gerätenamen angehängt (Sparkonto (CHF)). Geschlossene Konten, ausgeblendete Kategorien (oder in einer ausgeblendeten Gruppe) und Einnahmekategorien werden weggelassen. Die Werte sind die des laufenden Monats, in der Zeitzone von Gladys.

Umschlag verbraucht ist das in diesem Monat Ausgegebene im Verhältnis zum Geld, das der Umschlag hatte: das Budgetierte plus der Übertrag des Vormonats. Ein Umschlag, aus dem leer ausgegeben wurde, zeigt 1000 %, die Obergrenze.

Um bei einem Kontostand unter einer Schwelle gewarnt zu werden, nutze den Standard-Auslöser von Gladys „Gerätezustandsänderung“ auf den Kontostand des Kontos, mit der Bedingung „kleiner“: kein Auslöser der Integration nötig. Ebenso für das zu budgetierende Geld.

Dashboard-Widget

Actual-Budget-Übersicht zeigt das zu budgetierende Geld (wenn das Monatsgerät hinzugefügt ist) und die zu Gladys hinzugefügten Konten mit ihrem Stand (rot wenn negativ), dann die hinzugefügten Kategorien (höchstens 8) mit Ausgegebenem und Übrigem und dem verbrauchten Anteil: grün unter 75 %, orange bis 100 %, rot wenn überzogen. Tippe auf eine Kategorie, um das Budgetierte zu sehen. Die Fußzeile nennt die Uhrzeit des letzten Lesens.

Szenen-Auslöser

• Actual Budget: Umschlagschwelle: die Ausgaben einer zu Gladys hinzugefügten Kategorie erreichen 50, 75, 90 oder 100 % ihres Geldes im Monat, oder die Kategorie ist überzogen (eins auswählen). Er löst einmal pro Schwelle und Monat aus. Die beim ersten Lesen der Kategorie schon erreichten Schwellen sind der Ausgangspunkt und lösen nichts aus. Variablen: Name, budgetiert, ausgegeben, übrig, verbrauchter Anteil (%), Währung und ein fertiger Satz.

Was ausgelöst wurde, bleibt in den Daten der Integration: ein Neustart löst nichts doppelt aus.

Szenen-Aktionen

• Actual Budget: Kontostände lesen: der Stand jedes hinzugefügten Kontos, in einem Satz. Ausgaben: text, count, total (Summe der Stände).
• Actual Budget: Umschläge lesen: das zu budgetierende Geld (Monatsgerät hinzugefügt), dann was jede hinzugefügte Kategorie ausgegeben hat und übrig hat. Ausgaben: text, count, over_count (überzogene Kategorien), to_budget.

Eine Aktion liest das Budget neu, wenn das letzte Lesen älter als das Aktualisierungsintervall ist.

Szenen-Beispiele

• Lebensmittel fast aufgebraucht: Auslöser „Umschlagschwelle“, 90 %, auf die Lebensmittel-Kategorie; Aktion: die Familie per Telegram mit {{triggerEvent.data.text}} benachrichtigen.
• Überzogen: Auslöser „Umschlagschwelle“, „Überzogen“, auf eine Kategorie; Aktion: eine Nachricht senden, um sie auszugleichen.
• Montagmorgen-Überblick: jeden Montag um 8 Uhr Aktion „Umschläge lesen“, dann {{output.text}} vom Lautsprecher der Küche vorlesen lassen.

Datenschutz und Daten

• Die Integration liest dein Budget und schreibt nie hinein.
• Die Passwörter speichert Gladys wie jede geheime Einstellung, sie werden nie in die Protokolle geschrieben.
• Die Protokolle enthalten nie einen Betrag, einen Konto- oder Kategorienamen, eine Sync-ID oder die Adresse des Servers, auch nicht im Debug-Modus: nur Anzahlen, Fehlercodes und Schwellen.
• Keine Kontonummer gelangt in Gladys. Konto- und Kategorienamen werden Gerätenamen, die du umbenennen kannst.
• Das Datenvolume der Integration hält eine lokale Kopie des Budgets (wie die Actual-App), damit ein Lesen nur das Geänderte herunterlädt. Diese Kopie ist nicht verschlüsselt, auch nicht bei einem Ende-zu-Ende-verschlüsselten Budget: schütze den Gladys-Rechner entsprechend. Die Kopie wird gelöscht, wenn ein anderer Server oder ein anderes Budget eingestellt wird, und bei jedem Neustart der Integration. Das Volume hält auch die schon ausgelösten Schwellen (Kennungen, Monate und Schwellen).

Fehlerbehebung

Meldung	Was tun
Der Actual-Server lehnt das Passwort ab	Prüfe das Passwort; ein Server mit OpenID-Anmeldung wird nicht unterstützt
Der Actual-Server antwortet nicht	Prüfe die Adresse vom Gladys-Rechner aus (Port 5006, http/https) und ob Actual läuft
Kein Budget mit dieser Sync-ID	Kopiere die Sync-ID erneut aus Einstellungen → Erweiterte Einstellungen anzeigen
Der Server hat mehrere Budgets	Gib die Sync-ID an: „Verbindung testen“ listet die Budgets mit ihrer
Dieses Budget ist Ende-zu-Ende-verschlüsselt	Gib sein Verschlüsselungspasswort an
Dieses Budget braucht eine neuere Version	Actual wurde aktualisiert: aktualisiere auch die Integration
Ein Gerät hat keinen Wert	Füge es im Tab „Entdecken“ hinzu: nur die hinzugefügten Geräte werden verfolgt

Die Protokolle der Integration (Integrationen → Actual Budget → Protokolle) sagen, was passiert ist; LOG_LEVEL=debug gibt mehr Details. Eine https-Adresse braucht ein Zertifikat, dem die Integration vertraut: bei einem selbstsignierten nutze die http-Adresse des Servers in deinem Netzwerk.

Grenzen

• Nur lesend: aus Gladys lässt sich keine Buchung anlegen.
• Ein Server, ein Budget; nur Anmeldung per Passwort (kein OpenID).
• Keine Umrechnung zwischen Währungen: Actual hat eine Währung pro Budget.
• Ein Tracking-Budget hat kein „Zu budgetieren“: diese Funktion bleibt leer.
• Die Werte folgen dem Aktualisierungsintervall: eine Buchung erscheint beim nächsten Lesen in Gladys. Der Bank-Sync wird von der Integration nicht gestartet.
• Jedes Lesen lädt das Actual-Paket für einige Sekunden (etwa 100 MB Speicher) und gibt es dann frei.
• Getestet gegen einen echten actual-server 26.10.0 in Docker, mit und ohne Ende-zu-Ende-Verschlüsselung, noch nicht auf einer Gladys-Installation mit echten Konten: Rückmeldungen sind willkommen.

Konfigurationseinstellungen

Diese Einstellungen fragt Actual Budget in seinem Konfigurationsbildschirm in Gladys ab.

Einstellung	Typ	Pflichtfeld	Beschreibung
Verbindung zu Actual Budget	section	Nein	Gib die Adresse deines Actual-Servers und sein Passwort an. Hat der Server mehrere Budgets, füge die Sync-ID des zu lesenden hinzu (Einstellungen → Erweiterte Einstellungen anzeigen). Füge dann die gewünschten Konten und Kategorien im Tab „Entdecken“ hinzu.
Adresse des Actual-Servers	string	Ja	Die Adresse, unter der du Actual öffnest, von Gladys aus erreichbar.
Server-Passwort	secret	Ja	Das Passwort, mit dem du dich bei Actual anmeldest. Nur lesend: die Integration schreibt nie in dein Budget. Von Gladys gespeichert, nie in die Protokolle geschrieben.
Sync-ID des Budgets	string	Nein	Leer: das einzige Budget des Servers. In Actual: Einstellungen → Erweiterte Einstellungen anzeigen → Sync-ID.
Verschlüsselungspasswort	secret	Nein	Nur für ein Ende-zu-Ende-verschlüsseltes Budget.
Währung	select	Nein	Währung der Beträge. Automatisch: die in Actual eingestellte Standardwährung, sonst Euro.
Aktualisierungsintervall	select	Nein	Wie oft Actual Budget gelesen wird. Dein Geld bewegt sich nicht sekündlich: 15 Minuten reichen.
Sprache der Texte	select	Nein	Namen der Funktionen (bei ihrer Erstellung) und Texte für die Szenen.

So installierst du Actual Budget in Gladys

1. Öffne in Gladys Integrationen: Actual Budget erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/guim31/gladys-actual:1.0.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-actual.

Actual Budget benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen

Actual Budget ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

• Alle Integrationen durchsuchen, native und aus der Community
• Deine eigene externe Integration bauen und veröffentlichen
• Quellcode auf GitHub — Quelle dieser Dokumentation

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂