123Erfasst Connector

Vorwort

Der 123Erfasst Connector ermöglicht den konfigurierbaren Transfer von Stammdaten aus Finance nach 123Erfasst. Jede Synchronisation wird durch Austauschdefinitionen gesteuert, die folgende Elemente festlegen:

• Filterregeln für auszuwählende Datensätze

• Firmengruppenzuordnung

• Feldmapping mit Optionen wie Tabellenfeldern, verknüpften Werten, festen Werten oder Transformationsfunktionen

Die Datenübertragung erfolgt entweder manuell oder automatisiert über die Aufgabenwarteschlange.

Konfiguration

Grundkonfiguration

Primärschlüssel

Steuert die Zuordnung aller Konfigurationselemente (Benutzer, Firmengruppen, Austauschdefinitionen). Ermöglicht mandantenspezifische Einstellungen durch individuelle Schlüsselvergabe.

Authentifizierung

Benutzername: API-User für 123Erfasst

Passwort: Passwort des API-Users

Basis-URL API: Standard-URL https://server.123erfasst.de/API

Mandantensteuerung

Alle Mandanten übertragen: Synchronisiert alle Mandanten unabhängig von Firmengruppen

Firmengruppe: Legt mandantenspezifische Filter fest (nur bei deaktivierter "Alle Mandanten"-Option relevant)

Mandantenendpunkt: Aktuell /stammdaten/elemente (Details siehe Kapitel "Endpunkte")

Diagnose

Fehler protokollieren: Aktivieren Sie dies nur temporär zur Fehleranalyse, da Protokolle sonst übermäßig wachsen.

FID-Einstellungen

FID Separator: Definiert Trennzeichen zwischen Mandant/Niederlassung/Primärschlüssel (für die Funktion CreateFIDUsingSetup)

FID Einrichtung: Festlegung der FID-Generierung:

• Mandant + Primärschlüssel

• Mandant + Niederlassung + Primärschlüssel

Bei mandantenübergreifenden Tabellen wird nur der Primärschlüssel verwendet

Austauschdefinitionen

Definieren Sie hier, welche Datensätze synchronisiert werden sollen:

Basiseinstellungen

Tabellennummer: Quelltabelle in Finance

Tabellenbezeichnung: Beschreibung der Tabelle

Beschreibung: Freitext zur Identifikation der Definition

Endpunkt-Konfiguration

Endpunkt Code Insert/Modify: Ziel-API für Datensynchronisation

Hinweis: Löschfunktionen (GET/Delete-Endpunkte) sind aktuell nicht implementiert

Filterregeln

Bedingung vorhanden: Zeigt an, ob aktive Filter existieren und ermöglicht deren Bearbeitung

Erweiterte Firmengruppen

Firmengruppe: Überschreibt die globale Firmengruppenzuordnung für diese Definition (z.B. separate Gruppen für Baustellen F1/F2)

Feldmapping

Das Feldmapping ist ein zentrales Element jeder Austauschdefinition. Es bestimmt, welche Daten aus den Quelltabellen in 123Erfasst übertragen werden. Neben direkten Feldzuordnungen stehen auch erweiterte Optionen zur Verfügung:

Quelltypen

Tabellenfeld: Direkter Bezug auf ein Feld der Quelltabelle

Fester Wert: Statischer, vordefinierter Wert

Funktion: Nutzung vordefinierter Transformations- oder Abfragefunktionen

Verknüpfte Tabelle: Datenabfrage aus relationalen Tabellen

Konfigurationsoptionen

Zielfeld: Entsprechendes Feld in der 123Erfasst-API

Tabellenfeld Nummer: (Bei Quelltyp "Tabellenfeld") Feldnummer in der Quelltabelle

Fester Wert/Funktion: (Bei Quelltyp "Fester Wert"/"Funktion") Wertzuweisung oder Funktionsauswahl

Verknüpfte Tabelle/Feldnummer: (Bei Quelltyp "Verknüpfte Tabelle") IDs der verknüpften Tabelle und des Zielfelds

Datentypen und -verarbeitung

Typ: Zieldatentyp (TEXT, INTEGER, DECIMAL, DATE, BOOLEAN, GUID)

Pflichtfeld: Erzwingt Datenübertragung, setzt Alternativwerte bei leeren Quellfeldern

Maximale Länge: Begrenzt die Zeichenanzahl für TEXT-Felder

Standardwert: Fallback-Wert bei fehlendem Quellwert

Funktionen

Spezielle Transformations- und Abfragefunktionen ermöglichen komplexe Datenmanipulationen:

• Wertermittlung aus 123Erfasst via API

• Bedingte Wertzuweisungen

• Feldvergleiche und -transformationen

Jede Funktion verfügt über individuelle Parameter, die über Navigieren, Parameter konfiguriert werden können.

Verfügbare Funktionen für das Feldmapping

GetValuesByID

Holt einen Wert aus einem spezifizierten 123Erfasst API-Endpunkt. Filtert standardmäßig nach FID, falls kein Filterfeld definiert ist.

Parameter:

• Endpoint: API-Endpunkt-Code

• ID/IDField: Filterungsfeld

• DataPerCompany: Mandantenspezifität der Daten

• Value: Abzurufender Wert (z.B. Ident)

• Type: Rückgabe-Datentyp

• FilterField: 123Erfasst-Filterfeld

• NLField: Niederlassungsfeld (falls aktiviert)

GetCompany

Ruft die Ident des 123-Elements aus dem Mandantenmapping ab.

Parameter:

• NLField: Niederlassungsfeld (falls aktiviert)

MapOptionToBoolean

Konvertiert ein Enum/Optionsfeld in einen Boolean-Wert.

Parameter:

• OptionField: Quell-Optionsfeld

• TrueValue: Integer-Wert für "true"

CreateFIDUsingSetup

Generiert die FID basierend auf den Einstellungen.

Parameter:

• IDField: ID-Quellfeld

• DataPerCompany: Mandantenspezifität

• NLField: Niederlassungsfeld (falls aktiviert)

GetValuesByIDForRelatedTable

Ähnlich wie GetValuesByID, bezieht die ID jedoch aus einer verknüpften Tabelle.

Parameter:

• Endpoint: API-Endpunkt-Code

• RelatedTableNo/RelatedFieldNo: Verknüpfte Tabelle und Feld

• TableFieldNo/FilterFieldNo: Verknüpfungsfelder

• DataPerCompany: Mandantenspezifität

• Value/Type: Abzurufender Wert und Datentyp

• APIFilterField: 123Erfasst-Filterfeld

• NLField: Niederlassungsfeld (falls aktiviert)

• DefaultValue: Fallback-Wert

GetValueByCondition

Gibt einen Wert basierend auf Bedingungen zurück.

Parameter:

• CONDITIONFIELDx/CONDITIONx: Bedingungsfelder und -werte

• THENVALUE: Rückgabewert bei erfüllter Bedingung

• ELSEVALUE: Rückgabewert bei nicht erfüllter Bedingung

CompareFieldValues

Vergleicht zwei Tabellenfelder und gibt einen Wert zurück.

Parameter:

• FIELDNUMBER: Zu vergleichendes Feld

• COMPAREFIELD: Vergleichsfeld

• OPERATOR: Vergleichsoperator

• THENVALUE/ELSEVALUE: Rückgabewerte

Bedingungen/Bedingung löschen

Mit "Bedingungen" wird die Filterseite für die gewählte Definition bzw. der dahinter liegenden Tabelle geöffnet. Gesetzte Filter können dann mit "Bedingung löschen" wieder gelöscht werden.

Standardmapping erstellen

Mit der Aktion "Standardmapping erstellen" ist es möglich standardisierte Austauschdefinitionen initial zu übernehmen. Dabei können die einzelnen Bereiche wie u. a. Kostenstellen, Projekte oder Personal ausgewählt werden. Das Standardmapping wird dann pro Einrichtung über die Auswahl des festgelegten Primärschlüssels erstellt. Nicht vorhandene Endpunkte werden dabei ebenfalls angelegt.

Endpunkte

Endpunkte der 123Erfasst API müssen im Connector hinterlegt werden (z.B. ELEMENTE: /stammdaten/elemente)

Mandantenmapping

Für die Übertragung ist es erforderlich, dass die Mandanten aus Finance und die Mandanten aus 123Erfasst gemappt werden. Im Mandantenmapping (unter Zugehörig) gibt es dafür jeweils eine Auswahl der Mandanten aus Finance und den Mandanten aus 123Erfasst. Das Mandantenmapping wirkt sich nicht auf die zu übertragenen Mandanten aus. Es sollte also vermieden werden, Mandanten außerhalb der Firmengruppe einem 123Erfasst-Mandanten zuzuordnen.

Fester Wert für FID

Der erzeugten FID wird dieser Wert, z. B. die Kurzbezeichnung des Mandanten vorangestellt.

Beispiel:

Personalnummer: 4711

Fester Wert für FID: 123

FID: 1234711

Niederlassung als Element

Sollten die Niederlassungen in 123Erfasst als eigener Mandant angelegt sein, wird das Feld "Niederlassung als Element" für die korrekte Ermittlung der Mandanten genutzt. In 123Erfasst muss die FID dann wie folgt aufgebaut sein: Fester Wert für FID + Niederlassungsnummer

Datenübertragung

Automatisierte Ausführung

Für die automatisierte Ausführung wird die Aufgabenwarteschlange mit der Codeunit 5539565 "BAU Connector 123 Transfer" verwendet.

Manuelle Ausführung

Die Daten jeder Austauschdefinition können ebenfalls manuell übertragen werden. Dafür steht in der Übersicht der Austauschdefinition die Aktion "Daten übertragen" zur Verfügung. Standardmäßig wird die aktuelle Definition vor gefiltert. Dieser Filter auf die Lfd. Nr. kann allerdings entfernt werden, sodass alle Definitionen der zugehörigen Einrichtung gefiltert und übertragen werden.