Connector
Der Connector verbindet Octoserv mit der Schnittstelle eines anderen Systems, zum Beispiel einem anderen CRM. Kontakte, Firmen und Deals gehen in beide Richtungen: Octoserv liest Datensätze aus dem anderen System, sendet eigene dorthin und nimmt Änderungen entgegen, sobald das andere System sie meldet. Angebote gehen nach außen. Jede Änderung steht im Journal des Datensatzes und trägt als Herkunft den Namen der Verbindung. Sie richten alles in der Oberfläche ein, ohne Programmierung.
Typische Fälle: ein anderes CRM parallel weiterführen, Leads aus einem Drittsystem übernehmen, Stammdaten zwischen zwei Systemen abgleichen.
Voraussetzungen und Rechte
- Modul: Der Connector ist ein Modul, das für Ihre Installation freigeschaltet sein muss. Er steht dann unter Funktionen › Connector.
- Recht Connector (Sehen): Verbindungen, ihre Zuordnung und ihre Läufe.
- Recht Verbindungen ändern: Verbindungen anlegen und ändern, das andere System abfragen und Läufe starten. Dieses Recht wird nicht von selbst vergeben; Administratoren haben es.
- Das andere System muss eine Schnittstelle im Internet anbieten (https) und Ihnen einen Zugangsschlüssel geben.
Verbindung anlegen
- Öffnen Sie Funktionen › Connector und klicken Sie auf Neue Verbindung.
- Wählen Sie eine Vorlage für ein bekanntes System (zum Beispiel HubSpot, Pipedrive, Salesforce, Zoho und weitere) oder tragen Sie alles selbst ein. Eine Vorlage bringt die Art der Anmeldung, die Pfade und eine Zuordnung der Felder mit.
- Geben Sie einen Namen ein.
- Tragen Sie die Adresse der Schnittstelle ein. Sie muss eine https-Adresse im Internet sein; Adressen im eigenen Netz und Adressen mit Zugangsdaten werden abgelehnt. Bei einer Vorlage ersetzen Sie den Platzhalter (Ihr Konto oder Ihre Instanz) durch den eigenen Namen.
- Klicken Sie auf Verbindung anlegen.
Die Verbindung startet angehalten. Sie führt nichts aus, bis Sie sie einschalten.
Verbindung und Schlüssel
- Authentifizierung: Wählen Sie, wie sich Octoserv beim anderen System anmeldet: ein Schlüssel in einem Header, ein Bearer-Token, Benutzername und Passwort, der Schlüssel als Benutzername, OAuth 2.0 oder die Vtiger-Sitzung (siehe Vorlage Vtiger).
- Zugangsschlüssel: Er wird im Tresor gespeichert, danach nie wieder angezeigt und geht nur im Header an das andere System, nie in der Adresse. Leer lassen heißt: den vorhandenen behalten. Schlüssel entfernen löscht ihn.
- Weitere Header: feste Angaben, die bei jedem Aufruf mitgehen, einer pro Zeile als „Name: Wert“. Der Schlüssel gehört nicht hierher, sondern in die Einstellung Anmeldung.
- Eingeschaltet: Eine angehaltene Verbindung führt nichts aus und nimmt keine Änderungen vom anderen System an.
- Verbindung testen: prüft, ob das andere System antwortet. Angezeigt werden nur der Status und die Namen der Felder des ersten Datensatzes.
Anmeldung mit OAuth 2.0 (Ihre eigene App)
Viele Systeme erlauben keinen festen Schlüssel, sondern nur eine Anmeldung über OAuth 2.0. Dafür legen Sie beim anderen System eine eigene App an. Octoserv bringt keine App mit, die für alle gilt: Der Zugang bleibt bei Ihnen.
- Wählen Sie bei der Verbindung unter Authentifizierung den Eintrag Anmeldung mit OAuth 2.0.
- Legen Sie beim anderen System eine App an. Tragen Sie dort die Rücksprungadresse ein, die Octoserv im Feld darunter anzeigt. Das ist einmalig.
- Tragen Sie in Octoserv ein: die Client-ID, das Client-Secret (es kommt in den Tresor, wie jeder Schlüssel), die Adresse der Anmeldung, die Adresse des Tokens und den Scope.
- Speichern Sie und klicken Sie auf Anmelden. Sie gehen zum anderen System, stimmen zu und kommen zu Octoserv zurück.
- Octoserv holt sich das Token mit PKCE, legt es im Tresor ab und erneuert es selbst, bevor es abläuft.
- Nimmt das andere System die Erneuerung nicht mehr an (Passwort geändert, Zugriff widerrufen), steht die Verbindung auf Neu anmelden. Es wird nichts in einer Schleife wiederholt. Klicken Sie dann einfach erneut auf Anmelden.
- Abmelden entfernt die Tokens.
Zuordnung der Felder
Je Objektart (Kontakte, Firmen) legen Sie fest, aus welchem Pfad gelesen und an welchen gesendet wird und welches Feld in Octoserv zu welchem Feld im anderen System gehört.
- Öffnen Sie die Karte Zuordnung und wählen Sie den Reiter Kontakte oder Firmen.
- Tragen Sie Lesen von (Pfad) ein, unterhalb der Adresse der Schnittstelle, zum Beispiel
contacts, und Senden an (Pfad). Ein neuer Datensatz wird dort mit POST angelegt, ein verknüpfter unter Pfad und Kennung aktualisiert. - Mit Felder des anderen Systems laden bekommen Sie dessen Feldnamen zur Auswahl.
- Klicken Sie auf Zeile hinzufügen: links Feld hier, mitte Feld dort (ein Punkt baut verschachtelte Felder, zum Beispiel
properties.email), dann optional ein Fester Wert, der das Feld im anderen System ersetzt. - Wählen Sie die Richtung je Zeile: in beide Richtungen, nur hinein oder nur hinaus.
- Klicken Sie auf Zuordnung speichern.
Es werden nur Felder geschrieben, die das andere System wirklich sendet. Ein leerer Name, Kontaktweg oder Adressteil löscht nie etwas. Vorschau der ersten Seite zeigt, was ein Lesen tun würde (angelegt, aktualisiert, ausgelassen), ohne etwas zu schreiben.
Abgleich, Lesen und Senden
- Schlüssel eines Kontakts: Ein Datensatz im anderen System wird über diesen Kontaktweg (E-Mail, Mobil oder WhatsApp) einem Kontakt zugeordnet. Der Schlüssel einer Firma ordnet Firmen zu, zum Beispiel über den Namen.
- Datensätze über den Schlüssel abgleichen: An: Ein nicht verknüpfter Datensatz wird dem Kontakt oder der Firma mit demselben Schlüssel zugeordnet. Aus: Nur bereits verknüpfte Datensätze werden aktualisiert, alle anderen neu angelegt. Die Verknüpfung eines Datensatzes gilt immer.
- Feld mit der Kennung eines Datensatzes und Wo die Liste in der Antwort steht: Namen oder Pfade in der Antwort des anderen Systems. Leer:
data,itemsoderresults, sonst die Antwort selbst. - Seiten: wie das andere System lange Listen aufteilt (zum Beispiel per Cursor, mit Pfad zur nächsten Seite und dem Namen des Cursors in der Anfrage) und Datensätze je Aufruf.
- Datensatz aktualisieren mit: PATCH oder eine andere Methode.
- Suchen, bevor im anderen System angelegt wird: ein Pfad mit
{value}für den Schlüssel, zum Beispielcontacts/search?email={value}. Ein vorhandener Datensatz wird verknüpft und nicht doppelt angelegt. - Werte, die nur beim Anlegen im anderen System gesendet werden: einer pro Zeile als „Feld: Wert“, zum Beispiel
status: new. - Änderungen sofort senden: Eine Änderung an einem Kontakt oder einer Firma geht innerhalb einer Minute an das andere System. Was von dort kam, wird nie zurückgesendet.
Datenschutz: Hat jemand die Löschung seiner Daten oder den Widerspruch verlangt, wird die Person nicht wieder angelegt. Gehört ein Kontaktweg schon einem anderen Kontakt, wird er nicht übernommen und im Lauf vermerkt, mit der Nummer des anderen Kontakts.
Werte für neue Kontakte
Status, Statuslevel, Quelle und Verantwortlicher werden nur beim Anlegen eines Kontakts über diese Verbindung gesetzt. Ein vorhandener Kontakt behält sie, was auch immer das andere System sendet. Ohne Verantwortlichen entscheiden die Regeln der Verteilung (siehe Außendienst-Zuordnung). Sendet das andere System ausdrücklich einen Status oder einen Verantwortlichen und ist das in der Zuordnung eingetragen, gilt das auch beim Aktualisieren.
Übersetzung von Werten
Hier legen Sie fest, was ein Wert des anderen Systems hier bedeutet: die Mitarbeiterkennung 17 wird zu einem Benutzer, ein Statustext zu einem Status. Ein Verantwortlicher muss ein Benutzer von Octoserv sein; ist er es nicht, wird er weggelassen und im Lauf vermerkt. Die Übersetzung gilt je Feld hier: Beim Verantwortlichen wählen Sie den Benutzer, bei einem Status schreiben Sie dessen Text.
Deals und Angebote
Neben Kontakten und Firmen kennt die Zuordnung zwei weitere Reiter: Deals und Angebote.
Deals gehen in beide Richtungen
Ein Deal des anderen Systems wird in Octoserv angelegt oder aktualisiert, mit Ereignissen im Journal und der Wahrscheinlichkeit der Phase. Umgekehrt gehen Deals aus Octoserv an das andere System.
- Ein Deal braucht einen Kontakt oder eine Firma. Octoserv findet sie über die ID drüben (wenn dieser Datensatz zuvor gelesen wurde), über die E-Mail-Adresse und bei Firmen über den Namen.
- Die Phase wird über ihren Text unter den Phasen der Pipeline gesucht. Kennt Octoserv den Text nicht, bleibt die Phase wie sie ist, und der Lauf nennt den Grund.
Angebote gehen nur nach außen
Ein Angebot ist ein Dokument mit Nummer, Positionen und PDF, das in Octoserv entsteht. Das andere System bekommt die Zahlen: Nummer, Titel, Status, Summen, Gültigkeit, den Kunden und, wenn bekannt, den Deal drüben. Es schreibt nie ein Angebot zurück.
Mit Änderungen sofort senden wandern Deals und die Statusänderungen der Angebote automatisch.
Vorlage Vtiger
Die Vorlage Vtiger CRM liest Kontakte, Organisationen und Potentiale. Als Authentifizierung wählen Sie Vtiger-Sitzung.
- Tragen Sie den Namen Ihrer Vtiger-Installation als Adresse ein.
- Tragen Sie Ihren Benutzernamen in das Feld Benutzername ein.
- Tragen Sie den Zugriffsschlüssel als Schlüssel ein. Sie finden ihn in Vtiger unter Meine Einstellungen.
Octoserv holt sich die Sitzung beim anderen System selbst und erneuert sie, wenn sie abgelaufen ist.
Änderungen aus dem anderen System
- Klicken Sie in der Karte Änderungen aus dem anderen System auf Adresse anlegen. Die Verbindung bekommt eine eigene Adresse.
- Tragen Sie die Adresse im anderen System als Ziel für Änderungen ein. Dieses sendet jede Änderung, sobald sie passiert.
- Der Zugangsschlüssel der Adresse wird einmal angezeigt. Er gehört im anderen System in den Header
Authorization: Bearer …, nie in die Adresse. - Mit Neuen Schlüssel anlegen wechseln Sie ihn. Der bisherige gilt noch 24 Stunden, damit das andere System ohne Lücke umgestellt werden kann.
Unter Letzte Lieferungen sehen Sie, was angenommen oder abgelehnt wurde. Adresse löschen beendet den Empfang.
Läufe
Mit Alles aus dem anderen System lesen und Alles an das andere System senden starten Sie einen Lauf. Speichern Sie vorher die Zuordnung. Ein Lauf arbeitet im Hintergrund in Abschnitten und läuft weiter, wenn Sie den Browser schließen. Pro Verbindung läuft immer nur einer, und er lässt sich abbrechen.
Die Karte Läufe zeigt, wie viele Datensätze angelegt, aktualisiert, ausgelassen oder fehlgeschlagen sind. Details nennt, was ausgelassen wurde und warum, ohne Namen und Adressen.
Beispiel aus dem Alltag
Was im Hintergrund passiert
- Jeder Aufruf prüft die Adresse erneut: nur https im Internet.
- Jede Änderung steht im Journal des Datensatzes, mit dem Namen der Verbindung als Herkunft.
- Der Schlüssel liegt im Tresor und erscheint weder in der Oberfläche noch in der Adresse.
Zusammenspiel mit anderen Funktionen
- Webhooks und API: Octoserv selbst meldet Ereignisse an andere Software, der Connector bindet ein anderes System mit seinem Datenbestand an.
- Import und Export: für einmalige Dateien statt laufender Verbindung.
- Dubletten, Datenschutzanfragen und Journal.
Häufige Fragen
Nach dem Anlegen passiert nichts.
Die Verbindung startet angehalten. Setzen Sie den Haken Eingeschaltet und speichern Sie.
Entstehen doppelte Kontakte?
Lassen Sie Datensätze über den Schlüssel abgleichen an und tragen Sie bei Suchen, bevor im anderen System angelegt wird den Suchpfad ein. Dann werden vorhandene Datensätze verknüpft.
Der Verantwortliche fehlt am Kontakt.
Der Wert des anderen Systems muss in der Übersetzung einem Benutzer von Octoserv zugeordnet sein. Sonst wird er weggelassen und im Lauf vermerkt.