Abacus anbinden: Drei Werte, die Sie nicht hartkodieren können

Abacus ist ein Schweizer ERP für kleine und mittlere Unternehmen, es deckt Finanzen, Lohn und Projektmanagement ab und erreicht die Teile des Marktes, die nie auf ein reines Browserprodukt gewechselt sind: Treuhänder, Baufirmen, Hersteller. Wer Software an Schweizer Unternehmen verkauft, findet es früh im Integrations-Backlog.

Es ist außerdem ein System, bei dem die Frage wo läuft es keine einzige Antwort hat. Abacus wird installiert, entweder auf dem eigenen Server des Kunden oder auf dem eines Hosting-Anbieters, und das ist kein Detail der Bereitstellung. Es ist der Grund, aus dem die nächsten vier Abschnitte existieren.

Alles, was eine Plattform sonst für Sie klärt, wird hier je Kunde geklärt. Welche Endpunkte existieren, wie viele Anfragen Sie senden dürfen, was sich abonnieren lässt, und sogar, wo die Protokolle landen.

Wenn Ihnen lieber wäre, diese Unterschiede würden aufgefangen statt behandelt, finden Sie auf der Seite zur Abacus-Schnittstelle die Objekt-für-Objekt-Sicht darauf, was eine Verbindung über uns trägt. Der Rest dieses Leitfadens sind die Folgen selbst, in der Reihenfolge, in der Sie ihnen begegnen.

Fangen wir mit dem Kleinsten an, das sonst keiner Erwähnung bedarf. Um einen Endpunkt aufzurufen, brauchen Sie einen Host, und bei Abacus gibt es keinen Host zum Hartkodieren. Jede Installation antwortet auf ihrer eigenen Adresse, und wo ein Anbieter mehrere Kunden hostet, kann sie sich zusätzlich je Mandant unterscheiden.

Die Basis-URL wird damit zu einem Feld im Onboarding. Sie reist als Query-Parameter am Authentifizierungsaufruf mit und wird zu diesem Kunden gespeichert, womit sie aus Ihrer Konfiguration verschwindet, sobald Sie mehr als einen haben.

Der Mandant ist der zweite Wert derselben Art. Abacus nennt ihn auf beiden Wegen den Mandanten; environmentName ist unser eigener Name für diese Ebene, und er ist das, wonach der REST-Weg fragt und was der Umgebungs-Endpunkt zurückgibt. Auf AbaConnect bleibt das Wort des Herstellers und der Wert steht beim Login fest.

Eine Folge landet außerhalb Ihres Codes. Weil Abacus auf der Maschine des Kunden läuft, tun das auch seine Protokolle. Das Protokollieren von Anfragen einzuschalten heißt, eine Properties-Datei in der Installation zu bearbeiten und eine Stufe wie ch.abacus.eapi.level = FINER zu setzen, danach erscheinen die Einträge im Protokollordner dieses Servers. Gespräche mit dem Support fangen hier damit an, dass jemand anderes eine Datei öffnet.

Abacus liefert jährlich eine Hauptversion aus, und die Schnittstelle kommt mit ihr. Das Entwicklerportal veröffentlicht keine einzelne Endpunktübersicht, sondern eine je Version, mit einem eigenen Änderungsprotokoll daneben. Ein Kunde auf 2024 und ein Kunde auf 2026 betreiben dasselbe Produkt und bieten Ihnen zwei verschiedene Kataloge.

Der Abstand ist sogar in einer Liste sichtbar, in der ihn niemand erwarten würde. Abacus 2026 veröffentlicht eine Entitätsmenge Absences; der Katalog von 2024 beginnt einen Eintrag später im Alphabet, weil es diese Entität dort nicht gibt. Multiplizieren Sie das mit ein paar hundert Zeilen, und Sie haben den Grund, warum eine Funktion für einen Kunden fertig und für einen anderen unmöglich sein kann.

Die Version erreicht sogar die Teile der Einrichtung, die Sie Formsache nennen würden. Die Login-Weiterleitung, die Sie für einen Servicebenutzer registrieren, trägt sie im Pfad, der Callback ist also versionsspezifisch und nicht mandantenspezifisch, und die Unterstützung für eine neue Ausgabe zu ergänzen ist ein Konfigurationsschritt und keine Codeänderung.

Das ist der Punkt, an dem ein normalisiertes Modell aufhört, bequem zu sein. Wenn zwei Kunden auf dieselbe Frage verschieden antworten, muss etwas entscheiden, was Ihr Produkt sieht, und das einmal zu tun ist der Zweck des Common Data Model.

Der REST-Weg nutzt OAuth, mit dem Authorization-Code- und dem Client-Credentials-Grant, beide geben ein JWT zurück. Was er nicht nutzt, ist ein gewöhnlicher Benutzer. Abacus will einen Servicebenutzer, angelegt im Integrationsassistenten, und die Definition ist streng: „Der angegebene Service-User kann auf Abacus nur über die verfügbaren Schnittstellen zugreifen (ein Zugriff auf die Abacus-Oberfläche ist nicht möglich).“

Zwei Einzelheiten darum herum lohnt es sich vor der ersten produktiven Verbindung zu kennen. Die erste ist eine Frist: „Bitte beachten Sie, dass die Integration innerhalb von 10 Tagen genehmigt werden muss, andernfalls wird sie deaktiviert.“ Eine Integration, die Ihr Kunde anlegt und dann zwei Wochen liegen lässt, ist weg.

Die zweite ist ein Fehlercode, der nicht bedeutet, was er sagt. Eine Token-Anfrage ohne den Content-Type für Formulare kommt als 404 zurück und nennt den Token-Pfad, statt der 400 oder 415, nach der Sie zuerst greifen würden. Abacus dokumentiert den genauen Rumpf, der irreführende Teil ist also mitdokumentiert.

Abacus veröffentlicht seine Grenzen. Es benennt drei Fenster und wendet sie gleichzeitig an, eine Minute, eine Stunde und einen Tag. Überschreiten Sie eines davon, bekommen Sie eine 429 mit einem kleinen JSON-Rumpf, der das Servlet und die abgewiesene URL nennt.

Die Zahl ist allerdings eine Eigenschaft der Version und nicht des Produkts. Das ist das dritte Mal, dass derselbe Satz in diesem Leitfaden auftaucht, und hier landet er in Ihrem Zeitplan: Ein Abgleich, der für einen Kunden auf 2026 bemessen ist, verbringt bei einem Kunden auf 2025 den Nachmittag mit Backoff.

Es gibt drei dokumentierte Wege, weniger auszugeben, und der dritte ändert die Rechnung. Ein $expand holt verwandte Entitäten in derselben Anfrage, ein Deep Insert schreibt sie in einer, und eine Batch-Anfrage zählt als eine einzige Anfrage gegen die Grenze, wie viele Operationen sie auch trägt.

Gegen dieses Budget gelesen zählt eine weitere Zahl: Eine Antwort gibt höchstens 100 Datensätze zurück, und weiter geht es mit dem @nextlink, den die Antwort mitträgt. Ein erster Abgleich von zwanzigtausend Kontakten sind also zweihundert Aufrufe, bevor Sie irgendetwas anderes tun, das Sie in dieser Minute vorhatten. Das Blättern verhält sich auf fast jedem System anders, und deshalb gibt es ein Weg, zu filtern und zu paginieren als eigene Schicht.

Abacus sendet Ihnen nichts. Es gibt keine Webhooks und keine Callbacks, und unsere eigenen Abdeckungsdaten verzeichnen für kein Objekt ein natives Event. Was es stattdessen bietet, liest sich leicht als Zustellung, weil es Abonnement heißt: Sie registrieren ein Topic, und Abacus hält fest, was sich geändert hat, bis Sie kommen und es abholen.

Die Schleife sind drei Aufrufe. SubscribeChanges registriert ein Topic unter einem Namen, den Sie wählen, ConsumeChanges gibt alles zurück, was noch nicht bestätigt ist, und AcknowledgeChanges leert den Stapel mit dem Schlüssel, der zurückkam. Der Mandant steht im Pfad aller drei, ein Kunde mit drei Mandanten lässt die Schleife also dreimal laufen.

Drei Regeln machen aus der Bequemlichkeit eine Aufgabe mit Frist. Mindestens einmal täglich abholen. Mindestens einmal täglich bestätigen, wenn es etwas zu bestätigen gibt. Und „Abonnements, über die mehr als 3 Tage lang keine Nachrichten abgeholt werden, werden automatisch entfernt“, was heißt, dass eine Störung über das Wochenende mit einem verschwundenen Abonnement enden kann statt mit einem wartenden Rückstand.

Was ankommt, ist eine Liste von Kennungen und keine Datensätze, auf jede Nachricht folgt also ein Lesezugriff. Und ein Satz in der Referenz ändert, wie Sie den Zeitstempel benutzen: „Pro geändertem Datensatz wird nur 1 Nachricht registriert. Wurden an einem Datensatz auf dem Abacus-Server mehrere Änderungen vorgenommen, verweist der Zeitstempel ‚CreatedOn‘ auf den Zeitpunkt der ersten Änderung.“

Eine Fortschrittsmarke, die auf diesem Zeitstempel aufbaut, sitzt früher als die letzte Änderung des Datensatzes.

Auch das Bestätigen ist ganz oder gar nicht: Ein Schlüssel leert den ganzen Stapel. Scheitern Sie mitten in der Verarbeitung, haben Sie die Wahl, Arbeit zu bestätigen, die Sie nicht beendet haben, oder alles noch einmal abzuholen.

AbaConnect ist der Weg, den Sie brauchen, wenn ein Kunde ein Modul betreibt, dessen Objekte die REST-Endpunkte nicht tragen. Es meldet sich mit Benutzername, Passwort und Mandant an und gibt ein Login-Token zurück. Von da an verhält es sich auf eine Weise, die zu lesen sich lohnt, bevor Sie darum herum entwerfen.

Jede Datenanfrage kommt mit einem IsFinished-Flag zurück, und der Wert entscheidet, ob Sie warten: Viele geben es beim ersten Aufruf als true zurück, während andere eine oder mehrere Abfrageschleifen mit der RequestID brauchen, die Sie bekommen haben, im Abstand von 100 bis 250 Millisekunden. Schreibzugriffe sind die, die gewöhnlich warten, Lesezugriffe tun es manchmal, und welches von beiden es wird, lässt sich vor dem Senden nicht erkennen. Solange das Flag false ist, ist diese Anfrage offen, und „eine offene Anfrage blockiert andere Anfragen in derselben Benutzersitzung, bis die RequestID geleert ist“.

Zwei weitere Eigenschaften verschärfen das. Ein Benutzer bekommt eine Sitzung, und „mehrere Benutzersitzungen für denselben Benutzer sind nicht möglich“. Und eine Sitzung hält einen Mandanten: Wechseln heißt abmelden und wieder anmelden. Anfragen nacheinander, ein Client, ein Mandant zur Zeit.

Das ist auch der eigentliche Grund hinter dem Rat, einen eigenen Integrationsbenutzer anzulegen. Wer sich mit demselben Konto im Abacus-Menü anmeldet, kann die Webservice-Sitzung beenden, danach scheitern Ihre Aufrufe mit einer ungültigen Sitzung, und seit Abacus V2018 müssen die Benutzernamen, die sich auf diesem Weg anmelden dürfen, ohnehin in einer Server-Konfigurationsdatei stehen.

Die Sitzungen selbst laufen nicht nach fester Uhr. Standardmäßig lebt eine Sitzung bis zur Abmeldung, wobei der Server eine schließt, die eine Weile untätig war, in den Worten der Dokumentation „z. B. 15 – 20 Minuten“. Zwei nützliche kleine Operationen stehen daneben: Ping prüft die Erreichbarkeit ohne Anmeldung, und IsAlive prüft, ob eine Sitzung noch da ist. Über maesn ist beides nicht Ihre Aufgabe: Wo eine Sitzung geschlossen wurde, meldet sich der nächste Aufruf vorher wieder an.

Eine Zeile aus derselben Familie gehört in eine Sicherheitsprüfung und nicht in einen Bauplan. Die Verbindung läuft über http oder https, je nach der URL, die man Ihnen gegeben hat, die Transportverschlüsselung ist hier also eine Eigenschaft davon, wie dieser Server eingerichtet wurde.

Über maesn bleibt die Form, aber die Buchführung wandert. Asynchrone Arbeit gibt eine taskId zurück, und GET /asyncTask/{taskId} meldet den Fortschritt und übergibt das Ergebnis, sobald es fertig ist.

Unsere eigene Liste der asynchronen Endpunkte enthält GET genauso wie POST auf Kontakten, Projekten und Buchungssätzen, und so sieht ein Warten auf der Leseseite von außen aus, und dieselbe Warteschlange ordnet die Anfragen je Mandant. Was das über Ordentlichkeit hinaus bringt, steht auf der Seite zu Asynchronous Processing.

Zwei Schnittstellen, eine davon SOAP, ein Katalog je Jahr und eine Änderungsliste mit Frist. Was wir davon abnehmen:

• Aus den drei Werten wird ein Schritt im Onboarding. Die Basis-URL kommt als Parameter bei der Authentifizierung an und wird je Mandant gespeichert, der Mandant reist am Aufruf mit, und keiner von beiden landet in Ihrer Konfiguration.
• Beide Wege kommen in einer Form an. Ob ein Kunde über die REST-Endpunkte oder über AbaConnect bedient wird, ein Kontakt erreicht Sie als Kontakt. Der SOAP-Umschlag bleibt auf unserer Seite und die IsFinished-Buchführung ebenso, einschließlich des Teils, in dem eine Anfrage gar keine braucht: Was Sie erreicht, ist eine Task-ID, wenn es etwas zu warten gibt.
• Asynchrone Arbeit hat eine Schnittstelle. Eine Task-ID und ein Status-Endpunkt, dieselben für die Systeme, die in eine Warteschlange schreiben, und die, die sofort antworten.
• Sandboxes gibt es auch dort, wo der Hersteller keine freie Testversion anbietet. Abacus und AbaBau sind zwei der Systeme, bei denen sich ein Test nicht einfach registrieren lässt, und wir stellen die Umgebung bereit.

Was bei Ihnen bleibt, und zwei davon sind Entscheidungen statt Aufgaben:

• Das Abfrageintervall. Abacus sendet keine nativen Events, die Abonnement-Topics decken also Stammdaten ab, und alles andere ist ein Lesezugriff in einem Rhythmus, den Sie wählen. Wie aktuell Ihr Produkt sein muss, ist eine Produktfrage.
• Auf welcher Version Ihre Kunden sind. Sie entscheidet, was existiert, und es lohnt sich, danach im Vertrieb zu fragen statt es in der Umsetzung herauszufinden.
• Die Einrichtung innerhalb der Installation. Die Anwendung mit eingeschalteter AbaConnect-Option installiert, ein Servicebenutzer mit genehmigter Integration, und ein Mandant, der für die Schnittstelle freigeschaltet ist. Abacus vermerkt Auswirkungen auf den Preis für die Zahl der freigeschalteten Mandanten, und die ausführlichen Bedingungen stehen in einem Artikel der Wissensdatenbank, der nur seinen Vertriebspartnern offensteht.