Technische Schnittstellenbeschreibung
Zuletzt aktualisiert Vor etwa 1 Monat
1 Zweck und Geltungsbereich
Die Integration NEVARIS Finance-Build 2.0 beschreibt den Datenaustausch zwischen NEVARIS Finance und NEVARIS Build. Die Integration ersetzt den bisherigen NEVIS-basierten Austausch durch eine bidirektionale API-Synchronisation auf Basis von OData und REST-Endpunkten. Der Austausch erfolgt für Stammdaten sowie für ausgewählte fachliche Prozesse zwischen NEVARIS Build und NEVARIS Finance.
2 Systemkontext
Die Dokumentation beschreibt zwei fachliche Integrationsbereiche:
· BIS (Business Integration Synchronisation) für die automatische Überwachung von Datenänderungen in Business Central mit Protokollierung und API-Bereitstellung für externe Systeme.
· BIC (Business Integration Commands) für die bidirektionale Schnittstelle zwischen NEVARIS Build und NEVARIS Finance mit spezialisierten API-Modulen.
Die Dokumentation umfasst Stammdatenobjekte, Prozessschnittstellen sowie Einrichtungs- und Betriebsaspekte der Integration.
3 Integrationsprinzip
Die Integration 2.0 ersetzt den bisherigen NEVIS-basierten Austausch durch eine moderne, bidirektionale API-Synchronisation. Für die Übertragung wird der Middleware Connector verwendet. Die Installation und Inbetriebnahme sind im aktuellen Download-Portal beschrieben. Die Implementierung basiert auf dem OData-Standard mit v2.0 und ermöglicht CRUD-Funktionalität über REST-Endpunkte. Die Synchronisation erfolgt nach Auslösung in beide Richtungen; für die Erstanlage dient Finance bei mehreren Stammdatenobjekten als führendes System.
4 Technische Grundlagen
4.1 API-Grundlagen
Die APIs werden als OData-basierte REST-Endpunkte mit den Entitäten GET, POST, PATCH und optional DELETE und folgenden Metadaten bereitgestellt:
4.2 Synchronisationslogik
Die Synchronisation erfolgt nach Auslösung. Der initiale Austausch erfolgt für mehrere Stammdatenobjekte von NEVARIS Finance nach NEVARIS Build. Nach der Erstanlage werden Änderungen bidirektional synchronisiert.
4.3 Änderungsprotokollierung
Die BIS-Funktionalität enthält eine Änderungsprotokollierung. Erfasst werden unter anderem Änderungsprotokoll Art, Mandant, Tabellennr., Satzdaten System Id, Primärschlüsselfelder als JsonText sowie API-Metadaten des zugehörigen Endpunkts.
5 BIS – Einrichtung und Betrieb
5.1 Einrichtung Geschäftsintegration
Die Setup-Karte „Einrichtung Geschäftsintegration“ enthält unter anderem folgende Felder:
5.2 Aktionen auf der Setup-Karte
5.3 Ersteinrichtung und Initialsynchronisation
Die Ersteinrichtung wird durch den Nevaris Professional Service unter Berücksichtigung der individuellen Projektsituation geplant und dann durchgeführt.
Bei der Inbetriebnahme der Integration 2.0 ist zu beachten, dass die Synchronisationsrichtung je Stammdatenobjekt festgelegt ist und nicht für alle Objekte identisch arbeitet.
Grundsätzlich werden mehrere Stammdatenobjekte initial von NEVARIS Finance nach NEVARIS Build übernommen; danach werden Änderungen für geeignete Objekte bidirektional synchronisiert.
Für Finance-geführte Objekte wie Mandanten, Sachkonten und Debitoren ist NEVARIS Finance als führende Quelle zu behandeln; Änderungen oder Neuanlagen sind in diesen Fällen nicht aus NEVARIS Build heraus führend vorzunehmen. Für Kostenstellen gilt ein Mischprinzip: initiale Übernahme aus Finance, spätere Änderungs-Synchronisation in beide Richtungen, Neuanlagen jedoch ausschließlich in Finance.
Adress- und Kontaktdaten sind für den Abgleich zwischen beiden Systemen vorgesehen; für Adressaten ist der Austausch ausdrücklich in beide Richtungen beschrieben.
Vor dem produktiven Erstabgleich sollten insbesondere Bestandsdaten geprüft und bereinigt werden, weil Integration 2.0 Datenabweichungen und Validierungsprobleme transparenter sichtbar macht als der frühere Austausch.
Für den Betrieb sind außerdem die BIS-Endpunkte, die Änderungsprotokollierung und die Geschäftsintegration korrekt einzurichten.
Stellen Sie sicher, dass die ServicesLanguage in der Business Central Instanz auf Deutsch eingestellt ist. Dies können Sie über die folgenden Business Central Shell Befehle prüfen bzw. setzen:
Get-NAVServerConfiguration -ServerInstance Name der Instanz, i. d. R. BAU -KeyName ServicesLanguage
Set-NAVServerConfiguration -ServerInstance Name der Instanz, i. d. R. BAU -KeyName ServicesLanguage -KeyValue de-DE
5.4 Datenvalidierung im Admintool
Das Admintool (kaufmännische Integration) enthält einen zusätzlichen Tab zur Datenvalidierung. Die Funktion prüft die Datensätze der NEVARIS Build-SQL-Datenbank gegen die Validierungsvorgaben von NEVARIS Finance und gibt alle Abweichungen in einem Protokoll aus. Geprüft wird ausschließlich die Build-Datenbank, da die einschränkenden Feldvorgaben in Finance bestehen und in Build nicht gelten. Die Prüfung verändert keine Daten in Build oder Finance und nimmt keine automatische Korrektur vor; die Bereinigung muss manuell durch den Kunden erfolgen.
5.4.1 Prüfumfang
5.4.2 Protokoll
Ergebnis der Prüfung ist ausschließlich eine prüfbare und nachvollziehbare Ausgabeliste als Log. Je Abweichung wird ein Logeintrag erzeugt, der System, Datensatz und Feld des Regelverstoßes ausweist.
5.4.3 Kennzeichen „Finance-Vorgabe“
Optional prüft das Tool, ob das Kennzeichen „Finance-Vorgabe“ für die Build-Datenbank gesetzt ist, und bietet an, es nachträglich zu setzen.
5.4.4 Verhalten der Synchronisation bei ungültigen Datensätzen
Der Versuch, einen ungültigen Datensatz in Finance einzufügen, führt zu einem geloggten Fehler ohne Job-Abbruch. Datensätze, deren Schlüsselfeld sich nur in der Groß-/Kleinschreibung unterscheidet, werden von Finance bei der Abfrage unterschieden, beim Einfügen jedoch nicht. Dies wird als Fehler protokolliert, ohne den Job abzubrechen. Auch Abfragen zur Prüfung, ob ein Datensatz in Finance bereits existiert führen bei Verstößen gegen Finance-Validierungsregeln zu keinem Job-Abbruch, , z. B. GET /postCodes?$filter=PostCode eq '12345' and City eq '…'.
5.4.5 Anwendung vor dem Erstabgleich
Wird für eine bestehende Build-Datenbank nachträglich die Finance-Anbindung aktiviert, ist die Datenvalidierung vor dem produktiven Erstabgleich auszuführen, um Pflichtfeld-, Längen- und Mehrfachdatensatz-Abweichungen im Bestand zu erkennen und manuell zu bereinigen.
6 Schnittstellenbereiche
6.1 BIS – Stammdaten mit Change-Tracking
Die Quellen nennen für die BIS-Gruppe unter anderem folgende API-Pages mit EntitySetName:
6.2 BI-Gruppe
Die Quellen nennen für die BI-Gruppe unter anderem folgende API-Pages mit EntitySetName:
6.3 BIC – Business Integration Commands
Die Quellen beschreiben zwölf BIC-Module:
7 Stammdatenobjekte
Die Dokumentation „Schnittstelle-2.0-NEVARIS-Finance-Build“ strukturiert die geschäftsrelevanten Stammdatenobjekte in folgende Bereiche:
7.1 Finanz- & Organisations-Stammdaten
Kostenstellen
Kostenstellentypen
Sachkonto
Debitoren
Vertragsart
Zahlungsbedingungen
Mandanten
Niederlassung
Sparte
Abteilungen
Funktionen
Bauleiter
7.2 Adress- & Kontakt-Stammdaten
Adressaten
Adressquellen
Adressen
Adresstypen
Adresse-Adresstyp-Zuordnung
Anreden
Gruppen
7.3 Klassifikationen & Artikel
Artikel
Gewerke
Branchen
Adresse-Gewerke-Zuordnung
Adresse-Branche-Zuordnung
Adresse-Zertifikat-Zuordnung
7.4 Qualifikationen & Compliance
Zertifikate
Sperrhinweise
7.5 Sprachen, Währungen, Geodaten
Währungen
Sprachen
Länder
Bundesländer
Landkreise
Postleitzahlen PLZ
8 Beispielhafte technische Spezifikation: Kostenstellen
8.1 Geschäftslogik
Der Austausch von Kostenstellen erfolgt über die MWC/API. Der initiale Austausch erfolgt von Finance nach Build. Nach der Erstanlage funktioniert der Austausch von Änderungen bidirektional; die Neuanlage von Kostenstellen erfolgt ausschließlich in Finance.
8.2 Prozesskontext
Die Kostenstellen-Entität bildet die Grundlage für Projektsteuerung, Kostenrechnung und Abrechnungsprozesse. Abhängigkeiten bestehen zu Niederlassung, Sparte, Kostenstellentyp und Auftraggeber.
8.3 API-Metadaten (Auszug)
8.4 Endpunkte (Auszug)
8.5 Datenmodell (Auszug)
8.6 Validierungsregeln (Auszug)
Für die API der Kostenstellen sind in den Quellen insbesondere folgende Validierungen beschrieben:
· Logische Prüfung der Felder IsFinished und FinalInvoiced.
· Prüfung der Datumskonsistenz von ConstructionStartDate und ConstructionEndDate.
· Pflichtfelder SystemId, Company, Code und Name.
· Systemseitige Befüllung und Validierung der Creation- und Modification-Felder.
· PascalCase für API-Feldnamen.
8.7 Fehlercodes
9 Wichtige Prozessschnittstellen
9.1 Auftrags- / Nachtragswerte
Auftrags- und Nachtragswerte werden für Auswertungen an die Baubetriebsabrechnung (BBA) bereitgestellt. Die Bereitstellung erfolgt im Prozess Abrechnung mit der Funktion „Auftragswerte bereitstellen“. Alternativ kann die Übergabe für mehrere Projekte über die Projektübersicht durchgeführt werden.
9.2 NU-Vergabe
Die Ausschreibung und Vergabe von Nachunternehmerleistung erfolgt in NEVARIS Build auf Basis des aktiven Auftrags. Die kaufmännische Abwicklung ist in NEVARIS Finance im Bereich NU-Vertrag angesiedelt. Über den Prozessschritt „Angebot beauftragen“ wird die Anlage eines NU-Vertrags über einen Assistenten unterstützt.
9.3 Rechnungen
Die Anlage von Rechnungen erfolgt in NEVARIS Build mit einem Assistenten über den Prozessschritt „Rechnungen anlegen“. Unter dem Reiter „Kontierung“ erfolgt die Eingabe der Rechnungskostenstelle, des Debitors, des Anzahlungsvorgangs und des Erlöskonto. Die Funktion „Freigabe zur Buchung“ übergibt die Rechnungsdaten an die kaufmännische Anwendung.
9.4 Zahlungen
In Finance ist initial die Einstellung „Datenaufbereitung für Build“ zu setzen. Zahlungen werden in Finance über „Finanzbuchhaltung > Tägliche Aktivitäten > Kontoauszüge oder Fibu Buch.-Blatt“ erfasst. In NEVARIS Build werden die Zahlungen im Prozess „Rechnungen verwalten“ in den Reiter „Zahlungen“ übernommen.
9.5 Plandaten
Das Modul „sendPlanningData“ erstellt Planungsbuchungszeilen im Planungsarbeitsblatt (BBA). Die Logik initialisiert ein Journal mit dem Source Code „PLA“ und erstellt pro Planungseintrag eine „BAU BBA ArbBl.“-Zeile mit Projekt, Kostenstelle, Kostenart, hierarchischer Position, Buchungsperiode, Menge, Betrag und Einheit.
10 Adress- und Materialbezug
Die Quellen beschreiben eine automatische und manuelle Aktualisierung bzw. Synchronisation der in NEVARIS Finance und Build vorhandenen Adressdaten, insbesondere Adresse, Mitarbeiter, Branche und Gewerk. Für Betriebsmittel und kaufmännische Artikel wird ein kaufmännischer Mandant zugeordnet. Diese Mandantenzuordnung stellt die Verknüpfung und Synchronisierung der technischen Betriebsmittel Material mit den kaufmännischen Artikeln her.
Für die Darstellung der Planwerte ist die Kostenart maßgeblich; diese kann an einer „Technik-Dummy-Artikel-Nr.“ aufgehängt sein. Projektbezogene Artikelpreise können von den drei „Standard-Preise je Betriebsmittel (Artikel)“ abweichen.
11 Betriebsrelevante Hinweise
Die Integration verwendet OData-basierte REST-Endpunkte.
Die Synchronisation ist trigger-basiert.
Für mehrere Stammdatenobjekte ist Finance das führende System für die Erstanlage.
BIS stellt Endpunktverwaltung und Änderungsprotokollierung bereit.
BIC stellt fachliche Befehls- und Prozessschnittstellen zwischen Build und Finance bereit.