Connector AFS

Generelle Informationen

DocBee bietet einen Connector für AFS an. Dieser Connector wird bei Ihnen installiert und greift auf die AFS Datenbank zu und synchronisiert die Daten mit Ihrem DocBee.

Wichtig: Falls Sie den AFS Connector benötigen, wenden Sie sich bitte an Ihren DocBee Support.

Umfang

Der AFS Connector hat folgenden Umfang:

• Unidirektional / Bidirektional Synchronisation von Stammdaten ( Kunden, Standorte, Kontakte )
• Unidirektionales Anlegen von Materialien aus AFS Artikeln
• Abrechnungsexport aus DocBee zu AFS

Installation

Der DocBee AFS Connector kann als Docker Container (empfohlen) oder als Anwendung ausgeführt werden.

Die Unterstützung als Anwendung wird bald eingestellt und es sollte auf Docker umgestellt werden.

Als Docker Container

Nachdem Sie das Docker Image (docbee_afs_connector_image.tar) zur Verfügung gestellt bekommen haben. Könnten Sie es wie folgt installieren:

docker load --input docbee_afs_connector_image.tar
docker run -d --restart unless-stopped --log-driver json-file --log-opt max-file=1 --log-opt max-size=100m -v <PFAD>:/docbee-connector --name docbee_afs_connector docbee/docbee_afs_connector:latest`
docker stop docbee_afs_connector

<PFAD> muss durch einen leeren Datei-Pfad auf ihrem System zeigen. In diesem Pfad wird die Konfiguration und benötigte SQLite Datenbank abgelegt.

Die Einstellung für --restart, --log-driver, --log-opt max-file und --log-opt max-size=100m sind optional, werden aber von uns empfohlen

Wir stoppen den Container hier gleich wieder um die Konfiguration-Datei (settings.xml) zu bekommen und diese zu ändern.

Env variables

Optional können noch folgende Umgebungsvariablen beim Anlegen des Docker Containers hinzugefügt werden.

Name	Standardwert	Beschreibung
CONNECTOR_MEMORY_USAGE	1g	Wie viel Speicher darf der Connector verwenden WICHTIG: Dieser Wert bedeutet nicht den absoluten Speicherbedarf dieser kann höher liegen
CONNECTOR_LOG_LEVEL	WARNING	Das Log Level des Connectors kann z.B. auf DEBUG gestellt werden falls weitere Informationen benötigt werden

Beispiel

Verwenden Sie z.B. folgenden Befehl um den Docker Container mit 2 GB zu starten und das Log Level auf DEBUG zustellen.

docker run -d --restart unless-stopped --log-driver json-file --log-opt max-file=1 --log-opt max-size=100m -v <PFAD>:/docbee-connector --env CONNECTOR_MEMORY_USAGE=2g --env CONNECTOR_LOG_LEVEL=DEBUG --name docbee_afs_connector docbee/docbee_afs_connector:latest`

Als Anwendung

Der DocBee AFS Connector ist eine Java Anwendung, die als normale Anwendung wie auch als Windows-Dienst oder UNIX-Daemon laufen kann. Um den Connector zu installieren und um ihn auszuführen, wird eine Java Runtime auf dem System benötigt.

Hinweis: Zum Ausführen der Installations-Routine und zum späteren Ausführen des Connectors wird aktuell Java 1.8 empfohlen.

GUI

Der DocBee AFS Connector kann über einen Installer installiert werden. Dafür klicken Sie doppelt auf die docbee-afs-connector-installer.jar

Dies startet eine Installations-Routine und installiert die benötigten Daten.

Hinweis: Es kann je nach Betriebssystem nötig sein, dass die Installation als Administrator ausgeführt werden muss.

Hinweis: Falls Ihre Datei einen anderen Namen haben sollte, ersetzen Sie bitte docbee-afs-connector-installer.jar durch Ihren Dateinamen.

Windows

Einige Windows Version unterstützen beim Ausführen von Java Anwendung kein "Ausführen als Administrator". Um die Installation trotzdem als Administrator auszuführen, können Sie eine .bat-Datei erzeugen mit folgendem Inhalt.

start %~dp0docbee-afs-connector-installer.jar

Hinweis: Falls Ihre Datei einen anderen Namen haben sollte, ersetzen Sie bitte docbee-afs-connector-installer.jar durch Ihren Dateinamen.

Diese .bat-Datei können Sie dann als Administrator ausführen.

Command Line

Sie können den DocBee AFS Connector auch über die Kommandozeile installieren. Dafür führen Sie bitte folgenden Befehl aus:

java -jar docbee-afs-connector-installer.jar -console

Dies startet eine Installations-Routine und installiert die benötigten Daten.

Hinweis: Es kann je nach Betriebssystem nötig sein, dass die Installation als Administrator ausgeführt werden muss.

Hinweis: Falls Ihre Datei einen anderen Namen haben sollte, ersetzen Sie bitte docbee-afs-connector-installer.jar durch Ihren Dateinamen.

Unix-Daemon (optional)

Falls Sie den Connector auf Unix System als Daemon installieren wollen, führen Sie bitte folgende Schritte aus:

1. Gehen Sie ins Installationsverzeichnis
2. Führen Sie yasjsw/bin/installDaemon.sh aus

Hinweis: Es kann je nach Betriebssystem nötig sein, dass die Installation als Administrator ausgeführt werden muss.

Windows Dienst (optional)

Falls Sie den Connector auf Windows System als Dienst installieren wollen, führen Sie bitte folgende Schritte aus:

1. Öffnen Sie eine Eingabeaufforderung und führen diese als Administrator aus
2. Gehen Sie ins Installationsverzeichnis ( z.B. cd C:\DocBee\AFSConnector\)
3. Führen Sie den Befehl installService.bat aus

Hinweis: Es kann je nach Betriebssystem nötig sein, dass die Installation als Administrator ausgeführt werden muss.

Konfiguration

Bevor Sie den Connector starten, müssen Sie noch Ihre Konfiguration einstellen.

Dafür gehen Sie ins Installationsverzeichnis und öffnen die settings.xml in einem Texteditor Ihrer Wahl.

Einstellungen

Generell

drone\task\repeatInterval

Definiert den Intervall in Minuten, wie häufig der Connector die Daten synchronisieren soll.

Wichtig: Ein intervall kleiner als 5 Minuten ist aktuell nicht erlaubt.

drone\task\syncDeleteInterval

Definiert einen speziellen Intervall in Minuten, wie häufig der Connector gelöschte Datensätze abgleichen soll.

Hinweis: Da der Abgleich von gelöschten Datensätzen je nach Datenmenge länger dauern kann, empfehlen wir hier einen Wert von mindestens 60 Minuten.

Wichtig: Der sepezielle Intervall wird niemals häufiger als der repeatInterval ausgeführt.

drone\task\syncMode

Definiert, wie die Daten zwischen AFS und DocBee ausgetauscht werden sollen.

Wert	Beschreibung
unidirectional	Stammdaten (Kunde, Standort, Kontakte) werden von AFS zu DocBee synchronisiert.
full_bidirectional	Stammdaten (Kunde, Standort, Kontakte) werden bidirektional zwischen AFS und DocBee synchronisiert.

drone\task\sendBillableDocBeeDocumentsAfs

Definiert, ob aus abrechenbaren Leistungen in DocBee AFS Aufträge erzeugt werden sollen. (true oder false )

Hinweis: Alle Leistungen, die nicht auf "nicht abrechnen" stehen bzw. keine Abrechnungsnummer haben, werden zu AFS exportiert.

drone\task\importMaterials

Definiert, ob Artikel aus AFS zu DocBee übertragen werden sollen. (true oder false )

DocBee

drone\docbee\resturl

Die URL zur REST API Ihres DocBees ( z.B. https://my.docbee.com/restApi/ )

drone\docbee\username

Username des DocBee Benutzers inklusive Kurzbezeichnung ( z.B. BEISPIEL/username )

Wichtig: Der verwendete Benutzer muss mindestens die Rechte haben, um Stammdaten anzulegen und braucht Zugriff auf die Abrechnungsdaten.

drone\docbee\password

Passwort des DocBee Benutzers.

drone\docbee\baseurl Die Basis URL zu Ihrem DOcBee ( z.B. https://my.docbee.com/ )

AFS

drone\afs\host

Die IP oder URL zur AFS Datenbank.

drone\afs\port

Der Port der AFS Datenbank.

drone\afs\username

Datenbank Benutzer, der zu Griff auf die AFS Datenbank hat.

drone\afs\password

Das Passwort des Datenbank Benutzers.

drone\afs\databasename

Der Datenbank-Name der AFS Datenbank ( z.B. afs_wawi_db )

drone\afs\mandant

Die verwendete Mandant-ID aus AFS.

drone\afs\ordertype

Die Auftrags-Art-ID aus AFS. Dies wird verwendet, um die Aufträge mit diesem Typ in AFS anzulegen bei der Abrechnung der Daten.

Hinweis: Muss nicht gesetzt werden, falls task/sendBillableDocBeeDocumentsAfs nicht aktiviert ist.

drone\afs\customertypes

Eine Liste von Kunden-Typen, die synchronisiert werden sollen, wobei ein Kunden-Typ als Standard (default="true") definiert werden muss, damit DocBee beim Anlegen von neuen Kunden diesen Typ verwenden kann.

Beispiel:

<customertypes>
    <type default="true">0</type>
    <type>1</type>
</customertypes>

drone\afs\materialgroups

Eine Liste von Warengruppen-IDs, die für den Materialien Export zu DocBee verwendet werden soll.

Beispiel:

<materialgroups>
    <group>1</group>
    <group>2</group>
</materialgroups>

Hinweis: Muss nicht gesetzt werden, falls task/importMaterials nicht aktiviert ist.

drone\afs\servicetypemapping

Definiert die Verknüpfung zwischen DocBee Leistungsarten und AFS Artikel und wie diese abgerechnet werden sollen.

Ein Eintrag besteht immer aus der Artikelnummer aus AFS und einem Abrechnungstypen.

Folgende Abrechnungstypen sind möglich:

Wert	Beschreibung
hourly_rate	Stundensatz => Die Zeit in Stunden wird als Menge verwendet
lump_sum	Pauschale => Jede Tätigkeit wird mit der Menge 1 abgerechnet
daily_rate	Tagessatz => Pro Mitarbeiter und pro Tag wird die Menge berechnet

Wichtig: Die Artikelnummer muss zusätzlich bei der Leistungsart in DocBee als Nummer hinterlegt werden!

Hinweis: Muss nicht gesetzt werden, falls task/sendBillableDocBeeDocumentsAfs nicht aktiviert ist.

drone\afs\traveltypemapping

Definiert die Verknüpfung zwischen DocBee Reisearten und AFS Artikel und wie diese abgerechnet werden sollen.

Ein Eintrag besteht immer aus der Artikelnummer aus AFS und einem Abrechnungstypen.

Folgende Abrechnungstypen sind möglich:

Wert	Beschreibung
hourly_rate	Stundensatz => Die Zeit in Stunden wird als Menge verwendet
lump_sum	Pauschale => Jede Tätigkeit wird mit der Menge 1 abgerechnet
kilometer_rate	Kilometersatz => Die Distanz in Kilometer wird als Menge verwendet

Wichtig: Die Artikelnummer muss zusätzlich bei der Reiseart in DocBee als Nummer hinterlegt werden!

Hinweis: Muss nicht gesetzt werden, falls task/sendBillableDocBeeDocumentsAfs nicht aktiviert ist.

drone\afs\defaultsendemail

Definiert, ob neue Kontakt aus AFS standardmäßig Sende Email aktiviert haben sollen (true oder false )

drone\afs\defaultsendemailifselected

Definiert, ob neue Kontakt aus AFS standardmäßig Sende Email (Ausgewählt) aktiviert haben sollen (true oder false )

DocBee Einstellungen

Damit der Connector ordnungsgemäß funktioniert, müssen in DocBee folgende Einstellungen vorgenommen werden:

1. Funktion AFS unter Administration -> Funktionen aktiviert werden (Falls dies bei Ihnen nicht zur Verfügung steht, wenden Sie sich bitte an Ihren DocBee Support)
2. Hinterlegen der AFS Artikelnummer als Nummer in Leistungsarten und Reisearten.
3. Hinterlegen der AFS Personalnummer in der Benutzerverwaltung.
4. Aktivieren der AFS Anbindung unter Administration -> Anbindungen -> AFS
5. Konfigurieren Sie die Einstellungen, wie Sie es in der settings.xml vorgenommen haben ( syncMode, importMaterials, .. )

Ausführen

Als Docker Container

Nachdem Sie den DocBee Standard Connector als Docker Container installiert und konfiguriert haben können Sie Ihn nun starten in dem Sie folgenden Befehl ausführen:

docker start docbee_default_connector

Als Anwendung

Nach dem Sie den DocBee AFS Connector installiert und konfiguriert haben, können Sie Ihn nun starten.

Sie können ihn entweder manuell starten, indem Sie im Installationsverzeichnis auf die docbee-connector.jar klicken oder ihn per Kommandozeilen-Befehl starten ( java -jar docbee-connector.jar)

Hinweis: Es kann je nach Betriebssystem nötig sein, dass die Anwendung als Administrator ausgeführt wird.

Windows Dienst (optional)

Um den Connector als Windows Dienst zu starten, können Sie im Installationsverzeichnis die startService.bat ausführen oder ihn unter Dienste in Windows aktivieren.

Unix-Daemon (optional)

Um den Connnector als Daemon zu starten, führen Sie im Installationsverzeichnis den Befehl yajsw\bin\startDaemon.sh aus oder verwenden Sie service docbee-afs-connector start

Anbindung an DocBee mit existierenden Stammdaten

Bei der Anbindung an ein DocBee mit schon gepflegten Stammdaten sind folgende Daten der Stammdaten zu befüllen, damit der Connector die korrekte Verknüpfung vornehmen kann.

Hinweis: Bitte überprüfen Sie die Daten vor dem ersten Ausführen, damit nicht doppelte Datensätze erzeugt werden.

Wichtig: Bei bidirektionaler Kommunikation würde aktuell die letzte Änderung gewinnen. Falls Sie bei der Ersteinrichtung die Daten aus AFS verwenden wollen, führen Sie bitte folgendes in Ihrer AFS Datenbank aus UPDATE adressen SET `Update` = NOW();.

Kunden

Die Kundennummern in DocBee müssen der Kundennummer in AFS entsprechen.

Standort

Die Strasse und die Postleitzahl in DocBee muss der Adresse in AFS entsprechen.

Kontakt

Der Name des Kontakts in DocBee muss dem Namen des Ansprechpartner (Vorname, Nachname) entsprechen.

Update

Als Docker Container

Um den Container zu aktualisieren, führen Sie folgende Befehle aus, nachdem Sie die neue Image-Datei(docbee_afs_connector_image.tar) erhalten haben.

docker stop docbee_afs_connector
docker rm docbee_afs_connector
docker load --input docbee_afs_connector_image.tar
docker run -d --restart unless-stopped --log-driver json-file --log-opt max-file=1 --log-opt max-size=100m -v <PFAD>:/docbee-connector --name docbee_afs_connector docbee_afs_connector:latest`

<PFAD> muss durch den bei der Installation verwendeten Datei-Pfad ersetzt werden.

Sie müssen beim Update immer alle Parameter wieder übergeben, weil ein Docker Container komplett entfernt und dann komplett neu angelegt wird

Als Anwendung

Beim Aktualisieren als Anwendung können Sie einfach die Installation erneut ausführen und es in den gleichen Ordner installieren.

Sie sollten die Anwendung bzw. den Dienst/Daemon vorher stoppen

FAQ

Warum wurde in DocBee kein Kontakt für den Kunden angelegt?

In den Stammdaten in AFS muss ein Vorname und ein Nachname gesetzt sein, damit DocBee diesen als Kontakt importiert.

Warum startet der Dienst unter Windows nicht oder beendet sich sofort wieder?

Die auszuführende Java-Datei kann nicht gefunden werden.

Um dieses Problem zu beheben, gehen Sie bitte in das Installations-Verzeichnis des Connectors und dort in den Ordner yajsw\conf und öffnen Sie die Datei wrapper.conf mit einem Texteditor.

Ganz am Ende der Datei finden Sie wrapper.java.command = java. Diese java ersetzen Sie durch den vollständigen Pfad zur java.exe auf Ihrem System, ohne Dateiendung, z.B. wrapper.java.command = C:\\Java\\bin\\java.

Wichtig: Sie müssen bei Pfad \ durch \\ ersetzen, damit der Pfad richtig gefunden werden kann. z.B. muss der Pfad C:\pfad1\pfad2\ so hinterlegt werden C:\\pfad1\\pfad2\\.

Hinweis: Falls Sie die Java von Oracle installiert haben, finden Sie die java.exe aktuell unter C:\Program Files (x86)\Common Files\Oracle\Java\javapath ( wrapper.java.command = C:\\Program Files (x86)\\Common Files\\Oracle\\Java\\javapath\\java )

Wie migriere ich den Connector von Anwendung auf Docker Container?

1. settings.xml und store.sqlite.db des Connectors sichern
2. Die Anwendung deinstallieren über oder
3. Docker Engine installieren, falls noch nicht erfolgt
4. Docker Version des Connector installieren
5. Ausführung des Containers stoppen über docker stop docbee_afs_connector
6. settings.xml und store.sqlite.db in den Mount Pfad kopieren und die Dateien ersetzen
7. docker start docbee_afs_connector