Twenty CRM und Kimai verbinden: Kunden hier, Zeiten dort

Wer Kundenkontakte in einem CRM pflegt und Arbeitszeiten in Kimai erfasst, kennt den Bruch dazwischen. Ein Auftrag wird gewonnen, jemand legt den Kunden im CRM an, und danach legt dieselbe Person denselben Kunden noch einmal in Kimai an. Zwei Wochen später heißt der eine „Müller GmbH“ und der andere „Mueller GmbH“, und die Frage, wie viele Stunden auf diesen Kunden gelaufen sind, ist nur noch per Hand zu beantworten.

Twenty ist ein Open-Source-CRM, das sich selbst hosten lässt, und es passt technisch ungewöhnlich gut zu Kimai. Wir haben beides bei uns gekoppelt und arbeiten täglich damit. Dieser Text erklärt, wie die Verbindung funktioniert, und benennt die eine Stelle, an der es unbequem wird.

Warum die beiden zusammenpassen

Drei Gemeinsamkeiten machen die Kopplung überhaupt erst angenehm.

Beide laufen auf Ihrer eigenen Infrastruktur. Kundendaten und Zeitdaten bleiben im selben Netz, oft auf demselben Server. Es geht kein Umweg über einen Drittanbieter, und der Datenschutzteil der Übung bleibt überschaubar.

Beide haben eine ordentliche Schnittstelle, und zwar dieselbe Art. In beiden Fällen erzeugen Sie einen Zugangsschlüssel, in Twenty unter Einstellungen bei API und Webhooks, in Kimai im Benutzerprofil, und schicken ihn danach bei jeder Anfrage mit. Der Schlüssel wird jeweils genau einmal angezeigt und danach nie wieder, was in der Praxis regelmäßig für Ärger sorgt. Wer ihn nicht sofort wegspeichert, legt einen neuen an.

Beide sind erweiterbar, ohne den Kern anzufassen. In Twenty legen Sie eigene Objekte und Felder in der Oberfläche an, und die Schnittstelle kann sofort damit umgehen, ohne dass jemand etwas nachbauen müsste. Kimai wiederum kennt Zusatzfelder an Kunde, Projekt, Tätigkeit und Zeiteintrag. Genau die brauchen wir gleich.

Die eine Stelle, an der es unbequem wird

Twenty kann von sich aus Bescheid sagen. Sie hinterlegen eine Adresse, und bei jeder Änderung schickt das System dorthin eine Nachricht: welches Ereignis, welcher Datensatz, wann. Das gibt es für alle Objekte, auch für selbst angelegte, jeweils beim Anlegen, Ändern und Löschen. Die Nachrichten sind signiert, sodass Ihr Empfänger prüfen kann, dass sie wirklich von Ihrem CRM stammen und unterwegs niemand etwas verändert hat.

Kimai bringt so etwas nicht mit. Es gibt keine ausgehenden Benachrichtigungen, die Sie in der Oberfläche einschalten könnten. Das ist kein Mangel an Offenheit, sondern schlicht nicht Teil des Funktionsumfangs. Es bestimmt aber die Architektur der ganzen Kopplung: Die eine Richtung reagiert auf Ereignisse, die andere muss nachfragen.

Richtung 1: das CRM meldet, Kimai legt an

Der Anlass ist meistens derselbe. Ein Auftrag wechselt auf die gewonnene Stufe, und ab jetzt sollen Stunden darauf gebucht werden können. Die Meldung aus Twenty trifft auf einen kleinen Dienst, der daraufhin in Kimai zwei Dinge tut: den Kunden anlegen, falls es ihn noch nicht gibt, und darunter das Projekt.

Das ist der unspektakuläre Teil. Kimai nimmt beides über die Schnittstelle entgegen, ein Kunde braucht kaum mehr als einen Namen, ein Projekt den Namen und die Zuordnung zum Kunden. Damit steht die Struktur, ohne dass jemand sie abgetippt hat.

Der eigentliche Trick: die Datensätze verheiraten

Wichtig ist, was direkt danach passiert. Ein Name ist kein Schlüssel. Sobald jemand im CRM „Müller GmbH“ in „Müller GmbH & Co. KG“ umbenennt, ist jede Zuordnung über den Namen kaputt, und niemand merkt es, bis die Zahlen nicht mehr stimmen.

Deshalb hinterlegen Sie die Kennung aus dem CRM direkt am Kimai-Datensatz, in einem der Zusatzfelder. Von da an ist die Verbindung unabhängig davon, wie irgendwo etwas geschrieben wird. Umbenennungen, Rechtsformwechsel, Schreibfehler: alles egal, die beiden Datensätze wissen weiterhin voneinander.

Zwei Dinge dazu kosten Zeit, wenn man sie nicht vorher weiß. Erstens sind diese Zusatzfelder zwar Teil von Kimai, müssen aber über ein kleines eigenes Plugin angemeldet werden. Wer sie lieber in der Oberfläche verwalten möchte, nimmt das Custom-Fields-Plugin aus dem Kimai-Store. Zweitens hat jedes dieser Felder eine Sichtbarkeit, die zunächst ausgeschaltet ist. Erst wenn sie gesetzt ist, taucht das Feld auch in Schnittstelle, Export und Tabellen auf. Ein Feld, das Sie geschrieben haben und danach nirgends wiederfinden, ist fast immer dieser Fall.

Richtung 2: Kimai liefert die Zeiten zurück

Hier hilft keine Benachrichtigung, also muss der Dienst in einem festen Intervall nachfragen. Alle fünfzehn Minuten reicht für die meisten Betriebe vollkommen aus. Niemand braucht Stundenstände in Echtzeit im CRM, und ein seltenerer Takt schont beide Systeme.

Kimai liefert zu jedem Zeiteintrag alles, was die Gegenseite interessiert: Beginn, Ende, Dauer und Betrag, dazu zwei Kennzeichen, nämlich ob der Eintrag abrechenbar ist und ob er bereits in einen Export gelaufen ist. Über das zweite unterscheiden Sie sauber zwischen „schon abgerechnet“ und „steht noch offen“, was später für die Rechnungsstellung der entscheidende Punkt ist. Filtern lässt sich nach Kunde, Projekt und Tätigkeit.

Die Summe daraus wandert zurück ins CRM, am besten in ein eigenes Feld, das sonst niemand von Hand pflegt. Sonst überschreibt der nächtliche Abgleich irgendwann eine Angabe, die jemand bewusst dort eingetragen hat.

Ein Hinweis für den Fall, dass Sie das nachbauen: Die Schnittstellenbeschreibung Ihrer eigenen Kimai-Installation erreichen Sie unter dem Pfad /api/doc. Die ist versionsgenau, anders als jede Anleitung im Netz, und lässt sich in gängige Werkzeuge importieren.

Was Sie vorher wissen sollten

Grenzen der Schnittstelle. Twenty nimmt hundert Anfragen pro Minute entgegen und bis zu sechzig Datensätze je Anfrage. Für einen nächtlichen Abgleich über hundert Projekte heißt das: bündeln statt in der Schleife einzeln aufrufen.

Doppelte Meldungen. Eine Benachrichtigung kann zweimal ankommen. Prüfen Sie deshalb vor jedem Anlegen über die hinterlegte Kennung, ob es den Kunden in Kimai schon gibt. Sonst haben Sie das Duplikatproblem aus der Einleitung nur an eine andere Stelle verschoben.

Löschungen. Übertragen Sie Löschmeldungen nicht blind. Ein in Kimai gelöschter Kunde nimmt seine Zeiteinträge mit, und die sind Ihre Abrechnungsgrundlage. In der Praxis setzt man solche Datensätze auf unsichtbar, statt sie zu entfernen.

Zeitzonen. Kimai erwartet beim Schreiben eine lokale Zeit ohne Zeitzone und liefert beim Lesen eine Zeit mit Zeitzone zurück. Wer das verwechselt, hat Buchungen mit zwei Stunden Versatz und sucht lange nach der Ursache.

Der Dienst dazwischen. Beide Systeme sind offen, aber jemand muss die Übersetzung schreiben. Das ist kein großes Projekt, in der Regel ein paar hundert Zeilen und eine geplante Aufgabe im Hintergrund, aber es ist eben auch nicht nichts. Fertige Konnektoren für genau diese Kombination gibt es nach unserem Kenntnisstand nicht.

Wie das bei uns läuft

Das ist für uns kein Gedankenspiel. Wir betreiben Twenty selbst, hängen unsere eigenen Formulare daran und haben die Brücke zu Kimai gebaut, weil es sie fertig eben nicht gibt. Im laufenden Betrieb heißt das:

Kunden und Projekte stehen in beiden Systemen. Angelegt wird an einer Stelle, nämlich im CRM. Was in Kimai landet, kommt von dort und nicht aus einer zweiten Tipprunde. Die Namensdopplungen aus der Einleitung sind damit erledigt.

Der Projektstand steht im CRM. Die Zahlen aus Kimai laufen genau den Weg aus Richtung 2 zurück nach Twenty. Dort liegt der Stand eines Projekts als ganz normale Ansicht: neben dem, was vereinbart wurde, das, was tatsächlich gelaufen ist. Wer nachsehen will, wie weit etwas ist, öffnet ein System und nicht zwei.

Die Inventarisierung liegt als eigenes Objekt im CRM. Kundengeräte hängen am Unternehmen wie Kontakte und Aufträge auch. Zu einem Kunden gehören dadurch nicht nur Kontakt und Stunden, sondern auch seine Geräte. Für einen IT-Dienstleister ist das der Punkt, an dem aus zwei Werkzeugen eine Akte wird.

Der nächste Schritt ist die Anbindung an die Abrechnungssoftware. Die Daten dafür liegen längst richtig: Was abgerechnet werden kann, steht als Zeiteintrag in Kimai, und wem es zuzuordnen ist, weiß das CRM. Was fehlt, ist die letzte Übergabe.

Kimai ist ohnehin unser Spezialgebiet, von Templates über eigene Plugins bis zum laufenden Betrieb. Wenn bei Ihnen beide Systeme stehen und die Brücke fehlt, schauen wir uns das gern an. Meistens ist nach zwanzig Minuten klar, ob eine geplante Aufgabe im Hintergrund reicht oder ob es ein kleines Kimai-Plugin werden sollte: schreiben Sie uns kurz.