Funktionsweise und täglicher Betrieb
Sobald die Bridge gekoppelt und die Synchronisierung aktiviert ist, läuft sie von selbst. Diese Seite erklärt, was dabei tatsächlich geschieht, damit Sie im Zweifelsfall wissen, wo Sie nachsehen müssen, statt raten zu müssen.
Die Synchronisierungs-Engine in einfachen Worten
1. Eine Änderung erzeugt ein Ereignis
Jede relevante Änderung in WHMCS löst einen WHMCS-Hook aus: Ein Kunde wird angelegt oder bearbeitet, ein Kontakt wird erstellt, eine Rechnung wird finalisiert, eine Zahlung geht ein, eine Bestellung wird aufgegeben, ein Dienst wird bereitgestellt oder gesperrt, ein Ticket wird eröffnet oder beantwortet.
Der Hook führt keinen HTTP-Aufruf aus. Er schreibt ein kleines Ereignis in eine Outbox-Tabelle (mod_perfexbridge_outbox) und kehrt sofort zurück.
Würde ein WHMCS-Hook Perfex direkt aufrufen, könnte ein langsamer oder nicht erreichbarer Perfex-Server eine WHMCS-Verwaltungsseite oder den Bestellvorgang eines Kunden blockieren. Das Schreiben in eine lokale Tabelle dauert eine Millisekunde und kann niemals am Netzwerk eines Dritten scheitern. Alles Weitere geschieht im Hintergrund.
2. Der Cron leert die Warteschlange
Bei jedem Durchlauf des WHMCS-System-Crons entnimmt der Dispatcher der Outbox einen Stapel fälliger Ereignisse und sendet jedes davon per POST über HTTPS an Ihre Perfex-Installation.
Jede Anfrage trägt neben dem JSON-Körper zwei Header: einen Zeitstempel und eine HMAC-SHA256-Signatur, berechnet über diesen Zeitstempel plus den exakten Anfragekörper, mit Ihrem gemeinsamen Secret. Perfex berechnet die Signatur mit seiner eigenen Kopie des Secrets neu und weist alles zurück, was nicht übereinstimmt oder dessen Zeitstempel älter als 300 Sekunden ist.
Sie können das Leeren der Warteschlange jederzeit mit Run Sync Now auf der WHMCS-Modulseite sofort erzwingen.
3. Fehlgeschlagene Sendungen werden wiederholt und landen dann im Dead-Letter-Status
Eine fehlgeschlagene Sendung geht nicht verloren und wird nicht in einer engen Schleife wiederholt. Sie wird mit exponentiellem Backoff neu geplant: etwa 60 Sekunden nach dem ersten Fehlschlag, dann 2 Minuten, 4, 8 und so weiter, gedeckelt bei 6 Stunden zwischen den Versuchen.
Nach 15 Versuchen, was ungefähr 40 Stunden umfasst, wird die Zeile als dead markiert. Tote Zeilen werden nie automatisch wiederholt und nie aufgeräumt. Sie sind Ihre Dead-Letter-Schublade: Der Zähler Dead events oben auf der WHMCS-Modulseite nennt Ihnen die Anzahl, und die Protokollzeile nennt den Grund.
Dead-Lettering bedeutet, dass dasselbe Ereignis knapp zwei Tage lang aus demselben Grund fehlgeschlagen ist. Fast immer ist die Ursache eine von vier: eine in Perfex fehlende Währung, ein nicht übereinstimmendes Secret, ein Free-Plan, der ein Pro-Ereignis blockiert, oder ein offline befindliches Perfex. Beheben Sie die Ursache und reihen Sie die Arbeit erneut ein. Siehe Fehlerbehebung.
4. Pausieren führt zu keinem Datenverlust
Das Entfernen des Häkchens bei Enable Sync pausiert ausschließlich die Auslieferung. Die Hooks schreiben weiterhin Ereignisse in die Outbox, während der Pause geht also nichts verloren. Schalten Sie wieder ein, und der Rückstand wird beim nächsten Durchlauf abgearbeitet, oder sofort mit Run Sync Now.
5. Echo-Unterdrückung verhindert Endlosschleifen
Die Zwei-Wege-Synchronisierung birgt eine offensichtliche Gefahr: WHMCS übernimmt eine Änderung, die aus Perfex kam, dieser Schreibvorgang löst die eigenen WHMCS-Hooks aus, und die Änderung springt direkt zurück. Sich selbst überlassen, würde eine einzige Bearbeitung endlos hin und her pendeln.
Die Bridge verhindert das mit mehreren Schutzschichten, angewendet auf beiden Seiten:
- Eine Herkunftsmarkierung innerhalb der Anfrage, gesetzt, während die Bridge eine eingehende Änderung übernimmt, damit ihre eigenen Schreibvorgänge nicht als frische Benutzerbearbeitungen gelten.
- Ein Nachschlagen in der Entitäts- und Antwort-ID-Zuordnung, sodass eine gerade von der Bridge erzeugte Ticketantwort als solche erkannt und nicht erneut als neu versendet wird.
- Ein Prüfsummenvergleich, der ein Ereignis zu einer wirkungslosen Aktion macht, wenn die Daten dem zuletzt synchronisierten Stand bereits entsprechen.
Jede Seite hat ihre eigene Herkunftsmarkierung, und die Prüfsumme dient als Auffangnetz, falls eine Markierung einmal umgangen wird. Die Schutzmechanismen sind bewusst durchlässig ausgelegt: Kann ein Mechanismus nicht entscheiden, ist eine zusätzliche harmlose Sendung einer stillschweigend verworfenen Aktualisierung vorzuziehen.
6. Aufräumarbeiten
Beide Seiten führen ein selbstgedrosseltes tägliches Aufräumen durch, höchstens einmal alle 24 Stunden:
- ausgelieferte Outbox-Zeilen, die älter als 7 Tage sind, werden gelöscht;
- Protokollzeilen, die älter als 90 Tage sind, werden gelöscht;
- ausstehende und tote Zeilen werden nie aufgeräumt, denn ausstehend bedeutet noch nicht ausgelieferte Arbeit, und tot ist Ihre Dead-Letter-Schublade.
Was synchronisiert wird und in welcher Richtung
WHMCS nach Perfex CRM
| Daten | Free | Pro | Was in Perfex ankommt |
|---|---|---|---|
| 👥 Kunden | ✅ | ✅ | Ein Perfex-Kunde, dazu ein primärer Kontakt mit Name und E-Mail-Adresse des Kunden |
| 👤 Kontakte | ✅ | ✅ | Zusätzliche Kontakte unter demselben Perfex-Kunden |
| 🗑️ Kundenlöschung | ✅ | ✅ | Der Perfex-Kunde wird deaktiviert, nicht gelöscht |
| 📄 Rechnungen | ➖ | ✅ | Eine Perfex-Rechnung mit Positionen, einer Steuerzeile, übereinstimmenden Summen, Status und der WHMCS-Rechnungsnummer in der Verwaltungsnotiz |
| 💳 Zahlungen und Transaktionen | ➖ | ✅ | Ein Zahlungseintrag zur gespiegelten Rechnung, mit Zahlungsanbieter und Transaktions-ID. Duplikate werden abgewiesen |
| 💸 Erstattungen | ➖ | ✅ | Die Perfex-Spiegelung wird storniert und mit einem Vermerk versehen |
| 🛒 Bestellungen | ➖ | ✅ | Ein Perfex-Lead je Bestellung, oder eine Notiz beim Kunden, oder nichts, gemäß Order Sync Target |
| 📦 Dienste | ➖ | ✅ | Zeilen im Reiter WHMCS des Kunden: Produktname, Domain, Status, Abrechnungszyklus, Betrag und nächstes Fälligkeitsdatum |
| 🌐 Domains | ➖ | ✅ | Zeilen im selben Reiter: Registrar, Status, Ablauf und nächstes Fälligkeitsdatum |
| 🎫 Tickets und Antworten | ➖ | ✅ | Ein Perfex-Ticket beim Kunden, in der zugeordneten Abteilung, mit Antworten und Status |
Im Free-Plan werden Status und Notizen eines Kunden zwar in der Nutzlast übertragen, aber nicht nach Perfex geschrieben. Nur die Kundenlöschung wirkt sich auf den Perfex-Datensatz aus, indem der Kunde deaktiviert wird.
Perfex CRM nach WHMCS (nur Pro)
| In Perfex vorgenommene Änderung | Was in WHMCS geschieht |
|---|---|
| Firmendaten des Kunden bearbeitet | Der WHMCS-Kundendatensatz wird aktualisiert, vorbehaltlich der Konfliktregel |
| Primärer Kontakt bearbeitet | Die Identitätsfelder des WHMCS-Kunden werden aktualisiert, denn der primäre Kontakt ist die Kundenidentität |
| Nicht primärer Kontakt bearbeitet | Der passende WHMCS-Kontakt wird aktualisiert |
| Ein Mitarbeiter antwortet auf ein gespiegeltes Ticket | Die Antwort erscheint im WHMCS-Ticket, zugeschrieben Ihrem Ticket Reply Admin, sofern gesetzt, andernfalls dem Namen des Perfex-Mitarbeiters |
| Ticketstatus geändert | Der Status des WHMCS-Tickets zieht nach |
Das Löschen eines Kunden oder eines Datensatzes in Perfex löscht in WHMCS nichts. Abrechnungsdaten bleiben erhalten, unabhängig davon, was im CRM geschieht. Das ist Absicht und nicht konfigurierbar.
Bekannte Verhaltensweisen, die Sie kennen sollten, bevor Sie sich darauf verlassen
Dies sind dokumentierte Entscheidungen, keine Fehler:
- Direkt in Perfex erstellte Tickets bleiben in Perfex. Sie werden nie in WHMCS angelegt, denn ein WHMCS-Ticket benötigt ein Kundenkonto und eine Support-Abteilung, die einem CRM-seitigen Ticket möglicherweise fehlen.
- Ein über das vollständige Perfex-Formular für Ticketeinstellungen geänderter Ticketstatus wird nicht weitergegeben. Das Status-Dropdown eines einzelnen Tickets, Antworten, Massenstatusänderungen und das automatische Schließen synchronisieren dagegen korrekt.
- Zeit, die auf einer Perfex-Aufgabe je Ticket erfasst wird, wird nicht zurück nach WHMCS synchronisiert. Die Aufgabe existiert für die native Perfex-Timesheet-Auswertung.
- Der Rhythmus wiederkehrender Rechnungen wird nicht abgebildet. WHMCS-Rechnungen werden als einfache einmalige Perfex-Rechnungen gespiegelt.
- Das Zusammenführen zweier WHMCS-Kunden wird nicht behandelt. Ordnen Sie nach einer Zusammenführung die Zuordnungszeilen des aufgelösten Kunden neu zu oder entfernen Sie sie.
- Eine Antwort eines Perfex-Mitarbeiters auf ein synchronisiertes Ticket kann zwei Kunden-E-Mails erzeugen, eine von Perfex und eine von WHMCS. Wenn Ihre Kunden im WHMCS-Kundenportal zu Hause sind, deaktivieren Sie die Perfex-E-Mail-Vorlage
ticket-replyunter Setup > Email Templates > Tickets.
Wo die Protokolle zu finden sind
Dies ist der Abschnitt, der die meiste Zeit spart. Erfahrungsgemäß wird gewohnheitsmäßig an der falschen Stelle gesucht.
WHMCS-Seite: die eigene Modulseite
Gehen Sie zu Addons > Perfex CRM Bridge und scrollen Sie zu Recent activity.
Die Bridge schreibt nicht in das WHMCS Activity Log unter Utilities > Logs. Ihre eigene Tabelle wird als Panel Recent activity auf der Modulseite dargestellt, und das ist auf der WHMCS-Seite die einzige Stelle, an der Sie nachsehen müssen.
Die Tabelle zeigt die letzten 50 Ereignisse mit diesen Spalten:
| Spalte | Bedeutung |
|---|---|
| Time | Wann die Zeile geschrieben wurde |
| Dir | out für WHMCS nach Perfex, in für Perfex nach WHMCS |
| Event | Zum Beispiel client.upsert, invoice.upsert, cron.drain |
| Entity | client, contact, invoice, ticket und so weiter |
| WHMCS ID | Die WHMCS-ID des Datensatzes |
| Status | Grünes ok oder rotes error |
| Message | Das Ergebnis oder der genaue Fehlertext |
Direkt darüber zeigt die Kopfzeile die Zähler Queue pending und Dead events. Diese beiden Zahlen sind Ihre Gesundheitszusammenfassung: Der Bestand an ausstehenden Einträgen sollte innerhalb von ein bis zwei Cron-Zyklen auf null sinken, und der Zähler für tote Einträge sollte bei null bleiben.
Perfex-Seite: zwei Panels auf der Einstellungsseite
Gehen Sie zu Setup > WHMCS Bridge.
Recent inbound events listet auf, was WHMCS an diese Perfex-Installation gesendet hat, mit dem Ereignistyp, der WHMCS-ID, der zugeordneten Perfex-ID, einem Status-Abzeichen und einer Meldung. Hier erscheint eine abgewiesene Anfrage als Zeile auth.rejected, was auf ein Signatur- oder Zeitstempelproblem hinweist, fast immer auf ein nicht übereinstimmendes Secret. Abgewiesene Zeilen sind auf 10 pro Minute begrenzt, damit eine Flut Ihre Festplatte nicht füllen kann.
Outbound queue listet Änderungen der Perfex-Seite auf, die auf die Übertragung nach WHMCS warten, mit:
- den Zählern pending und dead in der Panel-Überschrift;
- einer Zeile je eingereihter Änderung mit Ereignis, Entität, Status, Anzahl der Versuche, Zeitpunkt des nächsten Versuchs und letztem Fehler;
- einer verständlichen Erklärung anstelle eines rohen Fehlers, sofern die Ursache bekannt ist. Ein 403 von einem WHMCS ohne Lizenz erscheint als "Two-way sync requires Pro on the WHMCS side" mit einem Upgrade-Link statt als JSON-Auszug.
Es werden nur die neuesten 20 Zeilen angezeigt. Ausgelieferte Zeilen räumen sich nach 7 Tagen selbst auf; ausstehende und tote Zeilen bleiben erhalten.
Welches Protokoll welche Frage beantwortet
| Frage | Hier nachsehen |
|---|---|
| 📤 Hat meine WHMCS-Änderung WHMCS verlassen? | WHMCS: Recent activity, Richtung out |
| 📥 Hat Perfex sie angenommen? | Perfex: Recent inbound events |
| 🔑 Ist mein gemeinsames Secret falsch? | Perfex: auth.rejected-Zeilen in Recent inbound events |
| 🔁 Hat meine Perfex-Änderung WHMCS erreicht? | Perfex: Outbound queue, danach WHMCS: Recent activity, Richtung in |
| ⏰ Läuft der Cron? | WHMCS: die Checklistenzeile Cron delivering |
| 🔇 Warum bleibt die Zwei-Wege-Synchronisierung stumm? | Perfex: das Panel WHMCS plan. Steht dort Free, haben Sie Ihre Antwort |
Der Backfill wizard (Pro)
Die Live-Synchronisierung erfasst ausschließlich neue Vorgänge. Wenn Sie die Bridge auf einer bereits etablierten WHMCS-Installation einrichten, sind Ihre bestehenden Kunden und Rechnungen erst dann in Perfex, wenn Sie sie nachträglich übertragen.
Der Backfill wizard befindet sich auf der WHMCS-Modulseite, unterhalb des Einstellungsformulars. Er reiht Ihre bestehenden Datensätze in dieselbe Outbox ein, die auch die Live-Synchronisierung nutzt, sodass sie dieselbe Signierung, dieselben Wiederholungen, denselben Backoff und dasselbe Dead-Lettering erben.
Bereiche
Haken Sie einen oder mehrere an:
| Bereich | Was eingereiht wird |
|---|---|
| Clients + contacts | Jeder Kunde im gewählten Zeitraum. Kontakte werden automatisch mit ihrem Kunden übertragen |
| Invoices | Jede Rechnung im gewählten Zeitraum |
| Services + domains | Jeder Dienst und jede Domain im gewählten Zeitraum, wodurch der Perfex-Reiter WHMCS gefüllt wird |
Historische Tickets werden nicht synchronisiert. Nur neue Ticketvorgänge fließen hinüber, nachdem die Bridge aktiv ist. Das ist eine dokumentierte Einschränkung, kein Konfigurationsproblem.
Modi
| Modus | Verhalten |
|---|---|
| All history | Jeder Datensatz in den gewählten Bereichen |
| Date range | Nur Datensätze, die innerhalb eines Zeitfensters von und bis im Format YYYY-MM-DD erstellt wurden. Ein ungültiger Zeitraum, zum Beispiel ein "from" nach dem "to", wird mit einer klaren Meldung abgelehnt, und es wird nichts eingereiht |
| Only new (not yet synced) | Überspringt bereits zugeordnete Datensätze. Das ist der Modus für wiederholte Durchläufe |
Die Grenze von 500 Entitäten und wie Sie fortfahren
Jeder Durchlauf reiht höchstens 500 Entitäten ein, sodass ein Backfill auf einer großen Installation weder die Warteschlange fluten noch Ihren Cron zum Stillstand bringen kann.
Wird die Grenze erreicht, teilt der Assistent Ihnen das mit. Der Ablauf ist:
- Klicken Sie auf Queue Backfill. Ein Informationsbanner meldet, wie viele Datensätze geplant, wie viele eingereiht wurden, wie viele fehlerhaft waren und ob der Durchlauf abgeschnitten wurde.
- Beobachten Sie, wie der Zähler Queue pending oben auf der Seite sinkt, entweder über den Cron oder mit Run Sync Now.
- Führen Sie den Assistenten erneut im Modus Only new (not yet synced) aus.
- Wiederholen Sie das, bis ein Durchlauf nichts Neues mehr einplant.
Es besteht kein Risiko von Duplikaten. Bereits zugeordnete Datensätze werden übersprungen, und ein Ereignis, dessen Daten der Perfex-Seite bereits entsprechen, wird als wirkungslose Aktion beantwortet.
Zwei Reihenfolge-Regeln, die Ihnen Zeit sparen
Ein untergeordneter Datensatz, dessen übergeordneter Kunde noch nicht in Perfex existiert, wird mit "not mapped, will retry" beantwortet und bleibt in der Warteschlange, bis der übergeordnete Datensatz eintrifft. Meist regelt die Reihenfolge der Warteschlange das von selbst. Wenn Sie jedoch ausschließlich Dienste oder Rechnungen auf einer Installation nachtragen, deren Kunden nie synchronisiert wurden, wiederholen sich diese Ereignisse etwa 40 Stunden lang und landen dann im Dead-Letter-Status.
Haken Sie entweder Clients + contacts im selben Durchlauf an, oder tragen Sie zuerst die Kunden nach.
Eine Rechnung in einer Währung, die Perfex nicht kennt, wird abgelehnt und wiederholt und landet nach etwa 40 Stunden im Dead-Letter-Status. Legen Sie vor dem Nachtragen von Rechnungen jede Währung, die Ihre WHMCS-Kunden verwenden, in Perfex unter Setup > Finance > Currencies an, jeweils mit dem exakten ISO-Code.
Historische bezahlte Rechnungen
Nachgetragene Rechnungen, die in WHMCS bereits bezahlt waren, werden in Perfex mit einem synthetischen Zahlungseintrag ausgeglichen, sodass sie als Paid und nicht als Overdue erscheinen. Ein erneuter Backfill-Durchlauf erzeugt keine doppelten Zahlungen.
Täglicher Betrieb
Sobald alles eingerichtet ist, gibt es sehr wenig zu tun. Ein kurzer wöchentlicher Blick auf die WHMCS-Modulseite genügt:
| Worauf Sie achten | Gesund |
|---|---|
| Setup checklist | Alles grün, mit Grau in der Lizenzzeile, wenn Sie Free nutzen |
| Queue pending | Klein und zwischen den Cron-Durchläufen sinkend |
| Dead events | 0 |
| Recent activity | Überwiegend ok-Zeilen |
| Perfex Outbound queue | 0 ausstehend, 0 tot, bei Pro-Installationen mit Zwei-Wege-Synchronisierung |
Stimmt etwas auf dieser Liste nicht, nennt Ihnen die Fehlerbehebung Ursache und Lösung.