Nuclet mit Funktionalität für den Import und die Verarbeitung von Dateien im MT940-Format
Name: | MT940 |
Package: | org.nuclet.mt940 |
Namensraum: | 940 |
Version: | 1.1.2 |
Datum: | 09.09.2013 |
Voraussetzungen ab Version 1.1.0
Ab Version 1.1.0 ist keine Währungsentität mehr im Nuclet enthalten. Eine Währungsentität muss also im Zielsystem existieren oder angelegt werden. Zwingend notwendig für diese Währungsentität ist, dass ein Attribut existiert, in dem der dreistellige ISO-4217-Währungscode als Identifizierungsmerkmal gespeichert wird (siehe dazu auch Wikipedia).
Überblick
Kurzbeschreibung
Das MT940-Nuclet bietet die Möglichkeit
elektronische Kontoauszüge, die im MT940-Format vorliegen, automatisiert einzulesen
die eingelesenen Daten in eine Struktur von Nuclos-Entitäten zu übertragen
die Bankumsätze anhand des Verwendungszwecks automatisch anderen Entitäten (je nach Anwendungszweck, bspw. Ihren Rechnungen) zuzuorden
Nuclet-Bestandteile
Das MT940-Nuclet umfasst im Rahmen der .nuclet-Datei
sieben Entitäten (für Kontoauszüge, Bankumsätze und diverse Stammdaten),
sechs Layouts,
ein Statusmodell (für Bankumsätze),
- zwei Attributgruppen,
diverse Java-Regeln (verteilt auf Packages),
eine Jobsteuerung (zur Steuerung des Import-Jobs),
drei Strukturdefinitionen (für den Import von Stammdaten) und
zwei Nuclet-Abhängigkeiten.
Darüberhinaus werden in der ZIP-Datei folgende Komponenten mitgeliefert:
drei CSV-Dateien für Objektimporte sowie
zwei MT940-Beispieldateien mit Kontauszügen.
Typ | Name, englisch | Name, deutsch | Kurzbeschreibung |
---|---|---|---|
Entität | Bank Statement | Kontoauszug |
|
| Bank Transaction | Bankumsatz |
|
| Bank Transaction Type | Bankgeschäftsvorfall |
|
| Banking Business Line | Bankgeschäftssparte |
|
| Debit/Credit Mark | Soll-Haben-Kennung |
|
| MT940 Reference | MT940-Referenz |
|
| Bank Transaction Ref | Referenz-2-Bankumsatz |
|
Layout | Bank Statement |
| Layout für Entität „Bank Statement“ |
| Bank Transaction, SINGLE |
| Layout für Entität „Bank Transaction“ |
Bank Transaction, MULTIPLE | alternatives Layout für die Entität „Bank Transaction“ mit Mehfachbezug | ||
| Bank Transaction Type |
| Layout für Entität „Bank Transaction Type“ |
| Banking Business Line |
| Layout für Entität „Banking Business Line“ |
| Debit/Credit Mark |
| Layout für Entität „Debit/Credit Mark“ |
Statusmodell | Bank Transaction |
| Statusmodell für die Entität „Bank Transaction“ |
Attributgruppe | Bank Transaction Data | Bankumsatz- und Kontoauszugsdaten | |
Bank Transaction References | den Bankumsätzen zugeordnete Refererenzen | ||
Java-Package | org.nuclet.mt940.job |
| Java-Regeln zur Steuerung von Jobs („Jobsteuerung“) |
org.nuclet.mt940.facade | Klassen für Datenbankzugriffe | ||
| org.nuclet.mt940.logic |
| Geschäftslogik |
| org.nuclet.mt940.parser |
| MT940-Parserfunktionalität |
| org.nuclet.mt940.rule |
| Steuerung von Insert-/Update-/Delete-Events |
org.nuclet.mt940.wrapper | Wrapper-Klassen (als Nuclet-Schnittstelle) | ||
Jobsteuerung | MT940 Import |
| Fristenjob für den automatisierten MT940-Import |
Strukturdefinition | Bank Transaction Type |
| Importstruktur für Entität „Bank Transaction Type“ |
| Banking Business Line |
| Importstruktur für Entität „Banking Business Line“ |
| Debit/Credit Mark |
| Importstruktur für Entität „Debit/Credit Mark“ |
Nuclet-Abhängigkeit |
| allgemeine Helferfunktionalität | |
Objektimporte | Banking_Business_Line.csv |
| Stammdatensätze für Entität „Banking Business Line“ |
| Bank_Transaction_Type.csv |
| Stammdatensätze für Entität „Bank Transaction Type“ |
| Debit_Credit_Mark.csv |
| Stammdatensätze für Entität „Debit/Credit Mark“ |
Beispieldateien | Kontoauszug_001.sta |
| MT940-Importbeispiel |
| Kontoauszug_002.sta |
| MT940-Importbeispiel |
Tabelle 1: Nuclet-Bestandteile
Achtung: Bitte beachten Sie, dass durch die Nuclet-Abhängigkeit zu org.nuclet.Common bei einer Integration des Nuclets weitere Komponenten ins System importiert werden, die hier nicht im einzelnen aufgeführt werden. Details zu den Bestandteilen des Common-Nuclets finden Sie in der Dokumentation dieses Nuclets.
Java-Package-Struktur
Die Java-Regeln sind in vier Packages unterteilt:
Regeln für maskengesteuerte Events (org.nuclet.mt940.rule)
Regeln zur Steuerung von System-Jobs (org.nuclet.mt940.job)
Regeln für die Geschäftslogik (org.nuclet.mt940.logic)
Regeln zum Einlesen und Verarbeiten von MT940-Dateien (org.nuclet.mt940.parser)
Die Abhängigkeiten der Packages sind in der folgenden Abbildung veranschaulicht.
In dreien dieser vier Java-Packages stellt eine abstrakte Java-Klasse die Basisfunktionalität über die deklarierten und (größtenteils) definierten Methoden. Die Import-Prozesse sind entlang der vordeklarierten Methoden dieser abstrakten Klassen festgelegt und bedürfen für den normalen Anwendungsfall keiner weiteren Anpassung.
Java-Package | abstrakte Klassen | konkrete Implementierungen |
org.nucket.mt940.job | AbstractMT940Importer | MT940Importer |
org.nuclet.mt940.logic | AbstractMT940Logic | MT940Logic |
org.nuclet.mt940.parser | AbstractMT940Parser | MT940Parser, MT940SparkasseParser |
org.nuclet.mt940.rule | - | - |
Tabelle 2: Java-Package-Struktur
Anwendungsspezifische Anpassungen sollten nur umgesetzt werden, entweder
in den konkreten, bereits vorhandenen, Klassen (siehe Tabelle) oder
durch neue, eigene konkrete Implementierungen
Das Package org.nuclet.mt940.parser enthält die Klasse MT940SparkasseParser, die bereits dezidiertes Verhalten für von Sparkassen gelieferte MT940-Dateien zur Verfügung stellt. Die zweite konkrete Implementierung innerhalb dieses Packages ist die Klasse MT940Parser, die über die Basisfunktionalität des AbstractMT940Parser hinaus kein zusätzliches Verhalten mitbringt. Für MT940-Dateien, die von anderen Kreditinstituten erstellt werden, müsste die Klasse MT940Parser (oder eine eigene, konkrete Implementierung des AbstractMT940Parser) ggf. mit bankspezifischem Verhalten gefüllt werden.
Das MT940-Nuclet ist zur Zeit derart konfiguriert, dass das sparkassenspezifische Verhalten genutzt wird. Die Initialisierung des Parsers erfolgt im Konstruktur der Klasse org.nuclet.mt940.job.MT940Importer und könnte dort jederzeit auf ein anderes Verhalten, d.h. eine eigene Implementierung umdirgiert werden.
public MT940Importer(final JobContext context, final String strMT940Directory, final String strMT940ReferenceType) { super(context, strMT940Directory, strMT940ReferenceType); // @replace! // // Replace with your own logic and/or your own parser here, if you // need more specific behaviour. // this.logic = new MT940Logic(context, strMT940ReferenceType); this.parser = new MT940SparkasseParser(context); }
Der Java-Sourcecode ist mit @replace!-Tags an all jenen Stellen markiert, wo anwendungsspezifisches Verhalten hinzugefügt werden kann. Dazu mehr im nächsten Abschnitt "Integration".
Integration
Notwendige Schritte zur Integration
Die Integration des MT940-Nuclets erfolgt in 8 Schritten:
Download
Nuclet-Import
Objektimporte anlegen
Objektimporte ausführen
Anpassungen im Entitäten-Wizard
- Layoutanpassungen
Einrichtung eines Eingangsverzeichnisses
Konfiguration der Systemparaemter (entfällt bis auf weiteres)
Sourcecode-Anpassungen in Java-Regeln
Alle Integrationschritte werden im folgenden im Detail erläutert.
Schritt 1: Download
Download der ZIP-Datei „MT940-v1.1.2.zip“ auf der Nuclos-Webpage unter „Nuclos Services“ > „Download“ > „Nuclet Download“. Das ZIP anschließend lokal entpacken.
Schritt 2: Nuclet-Import
Import des MT940-Nuclets unter „Konfiguration“ > „Nuclet Management“ > „Importieren“ in Ihre bestehende Nuclos-Instanz, Auswahl der Datei „MT940-v1.1.2.nuclet“
Beim Import werden Ihnen 4 Meldungen angezeigt:
- Entity Bank Transaction Ref references to unknown entity MT940 Reference. Redirect to dummy entity!
- Entity Bank Statement references to unknown entity Currency. Redirect to dummy entity!
- Entity Bank Transaction references to unknown entity MT940 Reference. Redirect to dummy entity!
- Entity Bank Transaction references to unknown entity Currency. Redirect to dummy entity!
-- diese Meldungen beziehen sich auf die Anpassungen, die im Schritt 5 von Ihnen vorzunehmen sind.
Schritt 3: Objektimporte anlegen
Objektimporte („Konfiguration“ > „Import & Export“) anlegen zu den Strukturdefinitionen „Bank Transaction Type“, „Banking Business Line“ und „Debit/Credit Mark“. Für die Importe können die mitgelieferten CSV-Dateien „Bank_Transaction_Type.csv“, „Banking_Business_Line.csv“ und „Debit_Credit_Mark.csv“ (zu finden im Unterverzeichnis „data“ der ZIP-Datei) verwendet werden.
Achtung: Es besteht eine Abhängigkeit zwischen „Bank Transaction Type“ und „Banking Business Line“; die Bankgeschäftssparten („Banking Business Line“) müssen vor den Bankgeschäftsvorfällen („Bank Transaction Type“) importiert werden.
Hinweis: Die CSV-Dateien beziehen sich auf die Spezifikationen der Sparkassen. Sollte das MT940-Format Ihrer Hausbank von der vorliegenden Implementierung abweichen bzw. sollten die Inhalte der MT940-Dateien hinsichtlich anders zu interpretieren sein, müssen Sie die zu importierenden Stammdaten selbst anlegen. Dies betrifft nur die beiden Entitäten „Banking Business Line“ (Bankgeschäftssparten) und „Bank Transaction Type“ (Bankgeschäftsvorfällen).
Schritt 4: Objektimporte ausführen
Die in Schritt 3 angelegten Objektimporte ausführen, so dass alle notwendigen Stammdaten im System sind.
Schritt 5: Anpassungen im Entitäten-Wizard
a) Eintragen der Währungsentität
In den Entitäten "Bankumsatz" und "Kontoauszug" wird eine Währungsentität referenziert, die nicht im MT940-Nuclet enthalten ist. Diese Referenzen müssen von auf die im Zielnuclet vorhandene und genutzte Währungsentität gesetzt werden.
b) Eintragen der Referenzentität
Variante SINGLE: In der Entität „Bankumsatz“ („Bank Transaction“) verweist das Attribut „Referenz“ („Reference“) auf ein Objekt vom Typ der Dummy-Entität „MT940-Referenz“ („MT940 Reference“). Dieses Referenz-Attribut dient der Zuordnung von Bankumsätzen zu Rechnungen, etc., je nach Anwendungszweck. Bitte über den Entitäten-Wizard das Attribut dahingehend bearbeiten, dass die für Sie richtige Entität referenziert wird.
Variante MULTIPLE: Für den Fall, dass es in Ihren Geschäftsprozessen üblich ist, einem Bankumsatz mehrere Referenzen (Rechnungen, o.a.) zuzuordnen, verwenden Sie bitte die Zwischenentität „Referenz-2-Bankumsatz“ („Bank Transaction Ref“). Diese Entität dient der Abbildung dieser n-m-Beziehungen. In diesem Fall müsste das Attribut „Referenz“ also in dieser Entität so angepasst werden, wie es für die erste Variante beschrieben wurde. Für die Variante MULTIPLE verwenden Sie bitte außerdem das Layout „Bank Transaction, MULTIPLE“ für die Bankumsätze; standardmäßig ist das Layout „Bank Transaction, SINGLE“ voreingestellt. Dafür müssten die zwei vorhandenen Verwendungen aus dem Layout „Bank Transaction, SINGLE“ entfernt werden und in das Layout „Bank Transaction, MULTIPLE“ eingetragen werden.
Die Java-Regeln lassen sich über den System-Parameter MT940_REFERENCE_TYPE auf die zu bevorzugte und zu verwendende Variante abstimmen; siehe dazu auch Schritt 7 (Konfiguration der System-Parameter).
Anmerkung: Eine weitere, denkbare Variante wäre, eine feste Anzahl (1-n) von Referenzen in der Entität Bankumsatz zuzulassen. Entität und Java-Regeln wären dementsprechend anzupassen.
Schritt 6: Layoutanpassungen
Nach Eintragen der verwendeten Referenzentität (Rechnung, o.ä.) in Schritt 5 kann das Layout dieser Referenzentität ergänzt werden. Empfohlen wird das Anlegen eines Unterformulars "Bankumsätze" (oder "Zahlungen", "Zahlungseingänge") in der verwendeten Referenzentität. Dieses Unterformular bildet dann alle zugeordneten Bankumsätze ab. Als verwendete Entität hier bitte also "Bankumsatz" auswählen, als Fremdschlüssel "reference".
Schritt 7: Einrichten eines Eingangsverzeichnisses
Einrichtung eines Dateiverzeichnis für den Eingang der MT940-Dateien. Das Verzeichnis sollte auf dem Server liegen
Schritt 8: Konfiguration der System-Parameter
Die Einrichtung der verwendeten Nuclos-Systemparameter über „Administration“ > „Parameter“.
Parameter | Kurzbeschreibung |
---|---|
MT940_DIRECTORY | Dateiverzeichnis für den Eingang von MT940-Dateien |
MT940_FILE_ENCODING | Zeichensatz der einzulesenden MT940-Dateien |
MT940_FILE_EXTENSION | Dateiendung der einzulesenden MT940-Dateien, alle anderen Dateitypen werden ignoriert |
MT940_REFERENCE_TYPE | verwendeter Referenz-Typus, unterstützt werden SINGLE und MULTIPLE |
Tabelle 3: System-Parameter
Anmerkung: Dieser Schritt wird erst in einer zukünfigen Version notwendig, d.h. sobald die neue Nuclos-API das Auslesen von System-Parametern unterstützt. Solange dies nicht der Fall ist, erfolgt die Konfiguration in Schritt 8, durch Anpassung von entsprechenden Konstanten im Java-Code.
Schritt 9: Sourcecode-Anpassungen in den Java-Regeln
Java-Package | Java-Klasse | Kurzbeschreibung | |
---|---|---|---|
a | org.nuclet.mt940.job | MT940ImportJob | Konfiguration des Eingangsverzeichnisses (MT940_DIRECTORY, s.o.) |
MT940ImportJob | Konfiguration des Zeichensatz der einzulesenden MT940-Dateien | ||
MT940ImportJob | Konfiguration des Dateiendung der einzulesenden MT940-Dateien | ||
| MT940ImportJob | Konfiguration des verwendeten Referenz-Typus (MT940_REFERENCE_TYPE) | |
b |
| MT940Importer | Behandlung des Referenzobjekts zu einem Bankumsatz nach erfolgter Zuordnung in Methode processReference() |
c | org.nuclet.mt940.logic | MT940Logic | Auslesen aller beim Import und der Zuordnung zu berücksichtigenden Referenzobjekte in Methode getReferences() |
d | org.nuclet.mt940.rule | CheckBankTransactionRef | Behandlung der Referenzobjekte beim manuellen Zuordnen/Entfernen zu/von einem Bankumsatz in Methode checkReferences() |
e | org.nuclet.mt940.wrapper | CurrencyWrapper | Wrapper-Objekt für Währungen, d.h. hier wird eine Schnittstelle zur tatsächlich genutzten Währungsentität definiert |
f | org.nuclet.mt940.facade | CurrencyFacade | Definition von notwendigen Datenbankzugriffen auf die tatsächlich genutzte Währungsentität |
Tabelle 4: Anwendungsspezifische Anpassungen in Java-Regeln
Alle notwendigen Anpassungen werden nun der Reihe nach, Klasse für Klasse, erläutert.
a) MT940ImportJob
Es ist notwendig, die beiden Konstanten MT940_DIRECTORY und MT940_REFERENCE_TYPE für den eigenen Anwendungszweck zu konfigurieren:
MT940_DIRECTORY: legt das Eingangsverzeichnis der MT940-Dateien fest
- MT940_FILE_ENCODING: definiert den Zeichensatz der einzulesenden Dateien
- MT940_FILE_EXTENSION: definiert die Dateiendung der einzulesenden Dateien
MT940_REFERENCE_TYPE: definiert, ob einem Bankumsatz genau eine (SINGLE) oder beliebig viele (MULTIPLE) Referenzen zugeordnet werden können.
@Rule(name="MT940 Import Job", description="MT940 Import Job") public class MT940ImportJob implements JobRule { // @replace! // // Configure the constants MT940_DIRECTORY, MT940_FILE_ENCODING, MT940_FILE_EXTENSION, MT940_REFERENCE_TYPE with your own values: // private static final String MT940_DIRECTORY = "/opt/nuclets/data/mt940"; private static final String MT940_FILE_ENCODING = "ISO-88591-15"; private static final String MT940_FILE_EXTENSION = ".sta"; private static final String MT940_REFERENCE_TYPE = "SINGLE"; // supported values are: { SINGLE, MULTIPLE } (...) }
Anmerkung: Dieser Schritt wird in einer zukünfigen Version entfallen, d.h. sobald die neue Nuclos-API das Auslesen von System-Parametern unterstützt. Sobald dies der Fall ist, wird diese Anpasung über Schritt 7 geregelt (s.o.).
b) MT940Importer
Die Methode processReference() wird während des Importvorgangs für jede einem Bankumsatz zugeordnete Referenz aufgerufen.
Wenn es sich in Ihrer Anwendung bei den Referenzen also z.B. um Kundenrechnungen handelt, dann ginge es an dieser Stelle um die Ausführung von Java-Code auf einer Kundenrechnung, zu der ein Bankumsatz gefunden wurde.
Denkbare Anweisungen hier wären bspw.
ein Markieren des Referenzobjekts als „zugeordnet“
ein Statuswechsel für das Referenzobjekt
das Auslösen von Berechnungsschritten, o.ä. auf dem Referenzobjekt
weitere Modifikationen auf dem Referenzobjekt oder auf Bezugsobjekten des Referenzobjekts (referenzierte Objekte, Unterformulareinträge, etc.)
/** * Process the reference, that has been linked to a bank transaction, accordingly * * @note This method has to be filled with application specific behaviour, * e.g. new calculations or further state changes on client billings, in case * client billings were the objects to be referenced by bank transactions * * @param reference a BusinessObject that has just been linked to a bank transaction * * @throws BusinessException might be thrown by implementing classes in case of errors * or other exceptions * */ protected void processReference(final BusinessObject reference) throws BusinessException { // @replace! // // Insert your code segment here that is to be executed on the references business object, // e.g. if your bank transactions are linked to client billings and the Nuclos-entity // representing your client billings was named "Client Billing", you would go on operating // an oject of type "ClientBilling" here: // // ClientBilling clientBilling = (ClientBilling)reference; // clientBilling.setIsReferenced(Boolean.TRUE); // clientBilling.setIncomingBankTransactionAt(new Date)); // clientBilling.setAmountOpen(...); // // StatemodelProvider.changeState(clientBilling, ClientBillingSM.State_N); // }
c) MT940Logic
Die Methode getReferences() wird vor dem Importvorgang ausgeführt. Sie dient dazu, alle bereits existierenden Objekte einzulesen, die beim Import der Bankumsätze als mögliche Referenzobjekte herangezogen werden sollen (bspw. Kundenrechnungen, die noch offen sind und nicht bereits zu einem Bankumsatz zugeordnet wurden).
An dieser Stelle sollte also eine Datenbankabfrage implementiert werden, die alle für eine Zuordnung in Frage kommenden Business-Objekte zurückliefert.
Das vorgefertigte und auszutauschende Fragment nutzt die in der Entität „Bankumsatz“ („Bank Transaction“) als Dummy-Referenz eingetragene (und zu ersetzende) BusinessObject-Klasse MT940Reference.
/** * Fetches all references that need to be considered during the MT940 import process, e.g. * all open client billings/invoices that have not yet been linked to other bank transactions * * @note A dummy implementation of <code>org.nuclet.mt940.logic.AbstractMt940Logic</code> has * been provided with this class here, its methods are meant to be implemented with user * specific behaviour. * * @return all references that need to be considered during the MT940 import process; the return * value comes as as <code>Map</code> in which the <code>BusinessObject</code> represents the * map's key while the text, which is meant to be used to link the reference to a bank * transaction, represents the map's value * * @throws BusinessException might be thrown in case of errors or other exceptions * */ public Map<BusinessObject, String> getReferences() throws BusinessException { final HashMap<BusinessObject, String> mpReferences = new HashMap<BusinessObject, String>(); // @replace! // Please, replace this code fragment here with your specific code fitting your needs. // // - MT940Reference is just a placeholder for the BusinessObject you'd like to use. // - If your aim was to link your client billings to your bank transactions, the client // billings being represented by the Nuclos-entity "Client Billing", you would use the // related BusinessObject-class "ClientBilling" here. // - Please, expand the query below to a more specific form. // // - In case only ClientBilling objects of two specific states should be considered, // a fitting code example could look like this: // // final Query<ClientBilling> qryGetReferencesStateAB = QueryProvider.create(ClientBilling.class); // qryGetReferencesStateAB.where(ClientBilling.NuclosState.eq(ProcessClientBillingSM.State_AB.getId())); // // final List<Rechnung> lstReferencesStateAB = QueryProvider.execute(qryGetReferencesStateAB); // // for (final ClientBilling clientBilling : lstReferencesStateAB) { // mpReferences.put(clientBilling, clientBilling.getBillingNumber()); // } // // final Query<ClientBilling> qryGetReferencesStateXY = QueryProvider.create(ClientBilling.class); // qryGetReferencesStateXY.where(ClientBilling.NuclosState.eq(ProcessClientBillingSM.State_XY.getId())); // // final List<ClientBilling> lstReferencesStateXY = QueryProvider.execute(qryGetReferencesStateXY); // // for (final ClientBilling clientBilling : lstReferencesStateXY) { // mpReferences.put(clientBilling, clientBilling.getBillingNumber()); // } // // return mpReferences; // return mpReferences; }
d) CheckBankTransactionRef
Bei der Klasse CheckBankTransactionRef handelt es sich um eine UpdateFinalRule. Sie ist der Entität „Bankumsatz“ („Bank Transaction“) zugeordnet. D.h. sie wird im Anschluss an ein Update eines Objektes vom Typ „Bankumsatz“ aufgerufen.
Ihre Methode checkReferences() ist dafür vorgesehen, im Rahmen eines solchen Update-Events notwendige Änderungen an den zugeordneten Referenzobjeten des Bankumsatzes auszulösen. Denkbar wäre dies bspw. für die folgenden Anwendungsfälle:
einem zuvor nicht referenzierten Bankumsatz wird eine Referenz hinzugefügt
aus einem zuvor referenzierten Bankumsatz wird die Referenz wieder entfernt
in einem zuvor referenzierten Bankumsatz wird alte Referenz gegen eine neue Referenz ausgetauscht
Diese Beispiele beziehen sich auf die Variante, in der jedem Bankumsatz maximal eine Referenz zugewiesen werden kann (MT940_REFERENCE_TYPE = SINGLE). Für den Modus MULTIPLE (ein Bankumsatz mehrere Referenzen besitzen) sind analog vergleichbare Anwendungsfälle denkbar.
Möglicherweise passende Anweisungen wären an dieser Stelle bspw.
ein Markieren des Referenzobjekts als „zugeordnet“/“nicht zugeordnet“
ein Statuswechsel für das Referenzobjekt
das Auslösen von Berechnungsschritten, o.ä. auf dem Referenzobjekt
weitere Modifikationen auf dem Referenzobjekt oder auf Bezugsobjekten des Referenzobjekts (referenzierte Objekte, Unterformulareinträge, etc.)
Unter Umständen wäre es sinnvoll, die zu implementierende Logik mit der Logik aus Punkt b) (MT940Importer) von oben abzugleichen.
Empfehlenswert wäre der Ansatz, die Funktionalität dafür in die Klasse MT940Logic (oder einer eigenen Unterklasse der AbstractMT940Logic) einzugliedern.
/** * Check, if the changes done to the given bank transaction should result in further * changes and/or state changes of the references <code>BusinessObject</code> * * @param context the current context * * @throws BusinessException, in case an error or exception occurs */ private void checkReferences(UpdateContext context) throws BusinessException { // @replace! // // This code segment needs to be filled with application specific behaviour. // // }
e) CurrencyWrapper
Die Klasse CurrencyWrapper dient als Nuclet-Schnittstelle zur tatsächlich genutzten Währungsentität. Der Konstruktor der Klasse und die Methode getIso4217Code() sind mit anwendungsspezifischem Verhalten zu befüllen. Letztere Methode sollte den ISO-4217-Währungscode (siehe dazu Wikipedia) des Währunsobjektes zurückliefern. Beispiele dazu sind in Kommentarblöcken angegeben; diese Beispiele sind bei der Integration also an die tatächlich genutzte Währungsentität (bzw. deren BusinessObject-Klasse) anzupassen.
package org.nuclet.mt940.wrapper; import org.nuclos.api.businessobject.BusinessObject; // @replace // // mit eigenem Code zu ersetzen, Beispiel: // // import org.nuclet.currency.Currency; /** * Konkrete Wrapper-Klasse für Währungsobjekte * */ public class CurrencyWrapper extends AbstractCurrencyWrapper { public CurrencyWrapper(final BusinessObject currency) { // @replace Bitte bei Nuclet-Integration mit eigenem Code ersetzen! // // Beispiel: // // if (currency instanceof Currency) { // this.businessObject = currency; // } } /** * Liefert die Datenbank-ID des Währungsobjektes. */ public Long getId() { return this.businessObject.getId(); } /** * Liefert den ISO-4217-Code des Währungsobjektes. * @see https://de.wikipedia.org/wiki/ISO_4217 * @see https://en.wikipedia.org/wiki/ISO_4217 */ public String getIso4217Code() { // @replace Bitte bei Nuclet-Integration mit eigenem Code ersetzen! // // Beispiel: // // return ((Currency)this.businessObject).getIso4217Code(); return null; } }
f) CurrencyFacade
In der Klasse CurrencyFacade muss die Methode getCurrencyByIso4217Code() mit anwendungsspezifischem Verhalten gefüllt werden. Die Methode erwartet einen ISO-4217-Währungscode (siehe Wikipedia) als Parameter und sollte ein Objekt vom Typ CurrencyWrapper (siehe Punkt e), oben) zurückgeben. Ein Beispiel dazu ist in einem Kommentarblock angegeben, dieses Beispiel ist an die tatächlich genutzte Währungsentität (bzw. deren BusinessObject-Klasse) anzupassen.
package org.nuclet.mt940.facade; import java.util.List; import org.nuclos.api.businessobject.Query; import org.nuclos.api.businessobject.QueryOperation; import org.nuclos.api.businessobject.SearchExpression; import org.nuclos.api.context.JobContext; import org.nuclos.api.context.RuleContext; import org.nuclos.api.exception.BusinessException; import org.nuclos.api.provider.QueryProvider; import org.nuclos.api.provider.BusinessObjectProvider; import org.nuclet.common.facade.AbstractFacade; import org.nuclet.mt940.wrapper.AbstractCurrencyWrapper; // @replace! Bitte bei Nuclet-Integration mit eigenem Code ersetzen! // // Beispiel: // // import org.nuclet.currency.Currency; /** * Facade for Business Objects of type "Currency" * */ public class CurrencyFacade extends AbstractCurrencyFacade { private static final CurrencyFacade instance = new CurrencyFacade(); /** * Liefert die Singleton-Instanz dieser Klasse * */ public static CurrencyFacade getInstance() { return instance; } /** * Fetches the currency which determined by a given ISO 4217 code from the database * * @param strIso4217Code the ISO 4217 code of the currency to be found * * @return the currency which is marked as "base currency" from the database * @throws BusinessException, if more than one currency-objects are found */ public AbstractCurrencyWrapper getCurrencyByIso4217Code(final String strIso4217Code) { // @replace! Bitte bei Nuclet-Integration mit eigenem Code ersetzen! // // Beispiel: // // // final Query<Currency> queryGetCurrency = QueryProvider.create(Currency.class); // queryGetCurrency.where(Currency.Iso4217Code.eq(strIso4217Code)); // // final List<Currency> lstCurrency = QueryProvider.execute(queryGetCurrency); // // if (lstCurrency != null && lstCurrency.size() > 0) { // return new CurrencyWrapper(lstCurrency.get(0)); // } else { // return null; // } return null; } }
Nutzung
Einrichten des Eingangsverzeichnisses
Das Verzeichnis, das in der Java-Klasse org.nuclet.mt940.MT940ImportJob als MT940_DIRECTORY angegeben wurde, muss auf dem Server existieren. Der Nuclos-Dienst benötigt für die Importvorgänge Lese- und Schreibrechte für dieses Verzeichnis und alle Unterverzeichnisse.
Innerhalb des MT940_DIRECTORY ist es notwendig, dass zwei Unterverzeichnisse „success“ und „failure“ eingerichtet sind. In diese Unterverzeichnisse werden die Dateien vom Import-Job nach erfolgter Ausführung verschoben.
Hinweis: Dateien, die vom Job verarbeitet werden konnten, werden im Verzeichnis „success“ abgelegt. Dateien, die nicht verarbeit werden konnten, findet man im Verzeichnis „failure“. Der jeweilige Dateiname wird um einen Zeitstempel ergänzt, so dass nachvollzogen werden kann, wann der Import-Job ausgeführt wurde.
Einrichten der Jobsteuerung
Öffnen der Jobsteuerung „MT940 Import“ unter „Administration“ > „Jobsteuerung“
Konfiguration von Startdatum, Startzeit, Intervall, E-Mail-Benachrichtigung und Optionen zum Löschen des Log-Infos.
Jobsteuerung aktivieren, falls der Job im konfigurierten Rhythmus automasiert ausgeführt werden soll. Alternativ lässe sich der Job über die Jobsteuerung auch manuell ausführen.
Betrieb
Die importierten Daten werden in den Entitäten für Kontoauszüge („Bank Statement“) und Bankumsätze („Bank Transaction“) gespeichert.
Die Masken für Kontoauszüge und Bankumsätze sind unter dem Menüpunkt „MT940“ zu finden. Dies ist über den Entitäten-Wizard jederzeit zu ändern.
Über den Menüpunkt „MT940“ > „Stammdaten“ sind die Stammdaten-Entitäten für Bankgeschäftssparten, Bankgeschäftsvorfälle und Soll-Haben-Kennung zu finden.
Einrichten von Benutzerrechten (optional)
Zugriffsrechte für existierende Benutzergruppen für Layouts, Entitäten, Attribute und Attributgruppen können in Nuclos wie üblich über drei Wege festgelegt werden (siehe dazu http://wiki.nuclos.de):
allemeine Einstellungen für Entitäten unter „Administration“ > „Benutzergruppen“
statusabhängige Einstellungen für Attribute/Attributgruppen unter „Konfiguration“ > „Statusmodell“
datensatzspezifische Einstellungen unter „Konfiguration“ > „Datenquellen“ > „Datensatzfreigabe“
Anmerkung: Sie sollten sich überlegen, inwieweit es Benutzern gestattet ist, Kontoauszüge und Bankumsätze manuell anzulegen oder zu löschen. Das MT940-Nuclet bietet dafür in der jetzigen Form noch keinerlei Unterstützung.
Beispiele
Die ZIP-Datei umfasst zwei MT940-Beispieldateien, diese sind im Unterverzeichnis „examples“ zu finden:
Kontoauszug_001.sta: ein Kontoauszug mit 5 Buchungen
Kontoauszug_002.sta:
Mit Hilfe dieser Dateien kann der Import-Prozess von Ihnen durchgespielt werden, selbst wenn Ihnen noch keine eigenen Dateien zur Verfügung stehen.
:20:STARTUMSE :25:10010010/1111111111 :28C:00001/001 :60F:C120131EUR8200,90 :61:1202020102DR400,62N033NONREF :86:077?00Überweisung beleglos?109310?20RECHNUNGSNR. 1210815 ?21K UNDENNR. 01234 ?22DATUM 01.02.2012?3020020020?2222222222?32MARTHA MUELLER?34999 :61:1202030103DR1210,00N012NONREF :86:008?00Dauerauftrag?107000?20MIETE GOETHESTR. 12?3030030030?31 3333333333?32ABC IMMOBILIEN GMBH?34997 :61:1202030103CR30,00N062NONREF :86:051?00Überweisungseingang?109265?20RECHNUNG 20120188?21STEFAN SCHMIDT?23KUNDENR. 4711,?3040040040?4444444444?32STEFAN SCHMIDT :61:1202030103CR89,97N060NONREF//000000000001 :86:052?00Überweisungseingang?109265?20RECHNUNG 20120165?21PETER PETERSEN?3050050050?315555555555?32PETER PETERSEN :62F:C120203EUR6710,50 -
:20:STARTUMSE :25:10050000/1111111111 :28C:00002/001 :60F:C120203EUR6710,50 :61:1202040515CR125,00N062NONREF :86:051?00Überweisungseingang?109263?20RECHNUNG 20120171?305005 0050?315555555555?32SUSANNE SCHNEIDER :61:1202040515CR389,45N061NONREF :86:051?00Überweisungseingang?109310?20FRITZ FISCHER?3060060060 ?316666666666?32FRITZ FISCHER :61:1202040515CR35,90N062NONREF :86:166?00Überweisungseingang?109249?20RECHNUNG 20120182 ?21AUF TRAGSNR. 1010?3070070070?317777777777?32WERNER WEBER?34888 :61:1202040516CR1015,10N062NONREF :86:051?00Überweisungseingang?109255?20RECHNUNG 20120179 ?21BES TELLUNG VOM?2231.01.2012?3080080080?3188888888?32MARLENE MEYER :61:1202050516CR610,80N062NONREF//661505129024 :86:051?00Überweisungseingang?109257?20RG. 20120164?3090090090? 319999999999?32WILLY WAGNER :61:1202050518CR3300,21N062NONREF :86:051?00Überweisungseingang?109267?20RECHNUNG BEATE BECKER?30 10110110?311212121212?32BEATE BECKER :62M:C120207EUR12186,96 - :20:STARTUMSE :25:10010010/1111111111 :28C:00002/002 :60M:C120207EUR5569,67 :61:1202050518CR61,00N060NONREF//000000000009 :86:052?00Überweisungseingang?109265?20RECHNUNG 20120185 ?30202 20220?312121212121?32SIEGFRID SCHULZ :61:1202080518DR99,80N011NONREF//013900139000 :86:005?00Lastschrift?109244?20ZAHLUNGSBELEG 08128128128?21IHRE KONTONR.1111111111?2208128128128/01.02.2012?3030330330?31343434 3434?32TELEKOMM GMBH :61:1202080518DR49,99N011NONREF//013900610875 :86:005?00Lastschrift?109244?20ZAHLUNGSBELEG 08128128129?21IHRE KONTONR.1111111111?2208128128129/01.02.2012?3030330330?31343434 3434?32TELEKOMM GMBH :61:1202090518DR99,80N011NONREF//013900238880 :86:005?00Lastschrift?109244?20ZAHLUNGSBELEG 08128128130?21IHRE KONTONR.1111111111?2208128128130/01.02.2012?3030330330?31343434 3434?32TELEKOMM GMBH :61:1202090518DR39,95N011NONREF//013900123445 :86:005?00Lastschrift?109244?20ZAHLUNGSBELEG 08128128131?21IHRE KONTONR.1111111111?2208128128131/01.02.2012?3030330330?31343434 3434?32TELEKOMM GMBH :61:1202100521CR560,60N062NONREF :86:051?00Überweisungseingang?109203?20RECHNUNG 20120186?304044 0440?314343434343?32HARRY HOFFMANN :62M:C120210EUR12519,02 - :20:STARTUMSE :25:10010010/1111111111 :28C:00002/003 :60M:C120210EUR12519,02 :61:1202110521CR444,28N062NONREF//661805129024 :86:051?00Überweisungseingang?109257?20RECHNUNG 20120178?3050550 550?315656565656?32SABINE SCHAEFER :61:1202120521DR240,00N033NONREF :86:020?00Überweisung beleglos?109310?20AUSLAGENERSTATT.BEWIRTUN G?21VERSAMML. 15.1.12?22RE VOM 1.2.12?23DATUM 02.02.2012, 11.53 UHR?3060660660?316565656565?32KARL KOCH?34997 :61:1202120521DR1500,00N033NONREF :86:020?00Überweisung beleglos?109310?20ABSCHLAG BERATUNG I/2012 ?21DATUM 01.02.2012, 11.56 UHR?3070770770?317878787878?32CLAUS&C LAUSEN KANZLEI?34997 :61:1202140522DR20,00N011NONREF//009879865431 :86:005?00Lastschrift?109264?206116113999 ZBNR 9879865431?21BELEG -NR. 6000336000?22B0011A5D90 899900122 PORTOK?23ASSEAUFLADUNG?24B ETRAG 20,00?3080880880?318787878787?32POST AG :61:1202150523CR65,10N062NONREF :86:051?00Überweisungseingang?109263?20RG.NR 20120169?21KUNDENNR. 9896?3090990990?319898989898?32BENNO BAUER :61:1202190523DR15,00N011NONREF//009879865431 :86:005?00Lastschrift?109264?206116113999 ZBNR 9879865431?21BELEG -NR. 6000336000?22B0011A5D90 899900127 PORTOK?23ASSEAUFLADUNG?24B ETRAG 15,00?3080880880?318787878787?32POST AG :62M:C120221EUR11733,40 -
Versionen
Version | Datum | Typ | Änderungen |
---|---|---|---|
1.0.0 | 12.03.2013 | initiale Version | - |
1.0.1 | 24.04.2013 | Fehlerkorrekturen |
|
1.1.0 | 08.08.2013 | erstes Änderungspaket | siehe Release Notes |
1.1.1 | 27.08.2013 | Erweiterungen bzgl. abweichender MT940-Formate | siehe Release Notes |
1.1.2 | 09.09.2013 | Bugfixes für v1.1.1 | siehe Release Notes |
1.2.0 | 13.09.2103 (geplant) | zweites Änderungspaket | |