Skip to content

Commit

Permalink
german translation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rsoika
rsoika committed Feb 11, 2025
1 parent d79c6f7 commit d074e04
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 61 deletions.
105 changes: 65 additions & 40 deletions imixs-adapters-datev/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,24 @@
# DATEV Adapter

DATEV is a comprehensive software and service platform primarily used by tax consultants, auditors, and accountants in Germany. It is designed to streamline and automate various aspects of financial accounting, payroll, tax filing, and business management. The **Imixs Datev Adapter** is a interface to import and export Imixs Workflow Data and DATEV Data in a bidirectional way.
Since DATEV is a German software system, the Imixs-DATEV Adapter module is exceptionally described in German language. In any case, you can also ask questions about this project at any time in English.

# Überblick

This adapter module provides services to import and export data from DATEV.
The import feature allows the import of DATEV master data like 'Kontenbeschriftungen'.
The export feature allows the export of workflow invoice data into a DATEV file (Buchungstapel).

## DATEV Import
Dieses Adaptermodul stellt Dienste zum Im- und Export von Daten aus DATEV zur Verfügung. Die Importfunktion ermöglicht den Import von DATEV-Stammdaten wie z.B. 'Kontenbeschriftungen' oder Debitoren/Kreditoren Stammdaten.
Die Exportfunktion ermöglicht den Export von Workflow-Belegdaten (z.B. Rechnungsdaten) in eine DATEV-Datei (Buchungstapel).

The imixs-datev-adapter provides mechanisms to import DATEV data. The import is based on the standard DATEV-Format which provides different data in CSV files.
## DATEV Import

### The DataImportService
Der imixs-datev-Adapter bietet Mechanismen zum Import von DATEV-Daten. Der Import basiert auf dem Standard-DATEV-Format, das verschiedene Daten in CSV-Dateien bereitstellt.

The DatevImportService EJB provides methods to read a Datev-Format file and import the data.
Die EJB `DatevImportService` stellt Methoden zur Verfügung, um eine Datei im Datev-Format zu lesen und die Daten zu importieren. Beispiel:

```java
// test if supported CSV file?
if (file.getName().endsWith(".csv")) {
ByteArrayInputStream input = new ByteArrayInputStream(file.getContent());
Expand All @@ -21,66 +28,81 @@ The DatevImportService EJB provides methods to read a Datev-Format file and impo
throw new PluginException(this.getClass().getName(), DatevImportService.IMPORT_ERROR,
"File Format not supported: " + file.getName());
}
```

The column 'Formatname' will be mapped to the item 'type'.
Die Spalte 'Formatname' wird dabei automatisch auf das `type` item gemapped.

#### Client and Consultant ID
#### Berater und Mandant ID

A DATEV-Format file contains a header with different information. The Datev 'Berater' and 'Mandant' are mapped to each imported dataset
Eine Datei im DATEV-Format enthält einen Header mit unterschiedlichen Informationen. Die Eigenschaften 'Berater' und 'Mandant' werden dabei jedem importierten Datensatz wie folgt zugeordnet

- Berater = \_datev_consultant_id
- Mandant = \_datev_client_id
- Berater = `datev.consultant.id`
- Mandant = `datev.client.id`

This item fields which are part of each imported datev dataset can be used to import data from different sources. The data can be selected by the items. There for the items must be added into the imixs.properties entry: 'lucence.indexFieldListNoAnalyze'
Diese Felder, die Teil jedes importierten datev-Datensatzes sind, können verwendet werden, um Daten aus verschiedenen Quellen zu importieren und zu benutzen. Für die lucene Suche wird beim Import ein generischer Primärschlüssel im item `name` in folgendem Format erzeugt:

lucence.indexFieldListNoAnalyze=....,_datev_client_id,_datev_consultant_id
`consultenID + "_" + clientID + "_" + keyValue`

#### Query DATEV data
Wobei hier das `keyValue` dem primärschlüssel des Datensatzes entspricht - beispielsweise der Kontonummer.

Data can be selected by a query based on the type and the categories. See the following example:
Daten können auf diese Weise durch eine einfache Abfrage basierend auf dem Typ und den Kategorien gesucht werden. Das folgende Beispiel sucht das konto mit der Nummer 1400 für den Berater/Mandant 00001/00001:

(type:"Kontenbeschriftungen" AND _datev_client_id:"00001" AND _datev_consultant_id:"00001")
(type:"Kontenbeschriftungen" AND name:"00001_00001_1400")

## DATEV Export

The DATEV Export is generated by a SignalAdapter within a Invoice Workflow model.
Der DATEV-Export kann über einen SignalAdapter innerhalb eines Workflow-Modells erzeugt werden.

org.imixs.workflow.datev.adapter.DATEVRefAddAdapter

The adapter automatically verifies if a DATEV Export for the current booking period and the `datev.client_id` already exists. If not, the adapter creates a new one.
Der Adapter prüft automatisch, ob bereits ein DATEV-Belegstapel Export für den aktuellen Buchungszeitraum und den 'datev.client.id' existiert. Ist dies nicht der Fall, erstellt der Adapter automatisch einen neuen Belegstapel und fügt den aktuellen Vorgang ein.

The DATEV Export Workflow can be fully controlled by the user
Für das Einfügen eines Beleges in den DATEV Belegsapel müssen im Workitem folgende Felder existieren:

<img src="datev-export-workflow.png" />
| item Name | DATEV Feld | Beispiel |
| ------------------ | ------------ | --------------- |
| datev.betrag | Umsatz | 67890,12 |
| datev.belegfeld1 | Belegfeld1 | Belegnummer 001 |
| datev.konto | Konto |
| datev.gegenkonto | Gegenkonto |
| datev.buschluessel | Buschluessel |

This model must at least define an initial Task with the following Events:
Auf diese weise können unterschiedliche Prozessdaten in einen Belegstapel zusammgefasst werden. Um ein Mapping eines workflow Items auf ein DATEV item zu erhalten kann dieses im BPMN Result event angelegt werden. Beisiel:

- add Invoice reference = 100
- remove invoice reference = 200
```xml
<item name="datev.betrag"><itemvalue>invoice.total</itemvalue></item>
<item name="datev.belegfeld1"><itemvalue>invoice.number</itemvalue></item>
<item name="datev.gegenkonto"><itemvalue>cdtr.number</itemvalue></item>
...
```

To remove a linked invoice the RemoveAdapter can be used.
Der DATEV Export Workflow kann vollständig über das DATEV Export Modell gesteuert werden.

<img src="datev-export-workflow.png" />

Um einen verknüpfte Vorgang aus dem Buchunsstapel zu entfernen, kann der RemoveAdapter verwendet werden.

org.imixs.workflow.datev.adapter.DATEVRefRemoveAdapter

To execute a SEPA Export the ExecuteAdatper can be used
Um den Buchunstapel zu erzeugen kann der ExecuteAdatper verwendet weden

org.imixs.workflow.datev.adapter.DATEVExecuteAdapter

### XSL Transformation

The DATEV file is generated using the imixs-report functionality. The DATEV report is assigned with a XSLT file to generate the output.
The DATEV file format is standardized. The DATEV interface is not public and not open source!
Die DATEV-Datei wird mit Hilfe der imixs-report-Funktionalität erzeugt. Dem DATEV-Report wird eine XSLT-Datei zugeordnet, um die Ausgabe zu erzeugen.
Das DATEV-Dateiformat ist standardisiert.
Für den DATEV Standard CSV Export muss ein Imixs Report definiert werden. Für das DATEV XML-Format sind zwei Reports erforderlich. Der Report für Belege definiert die Belegauswahl und das XSL, um einen Beleg in die entsprechende XML-Datei zu transformieren. Der Bericht für Dateianhänge (Belegbilder) wird benötigt, um die XSLT-Definition zu definieren, mit der die XML-Datei Dokument.xml generiert wird.

For the DATEV Standard CSV export one report need to be defined. For the DATEV XML format two reports a necessary. The report for invoices defines the invoice selection and the XSL to transform one invoice into the corresponding XML file. Thre report for documents is needed to define the XSLT definition to generate the XML file Dokument.xml.

**Note: ** The DATEV interface is not public and not open source! You need the official DATEV documentation to get information how the CSV and XML files have to be designed.
**Hinweis:** Die DATEV-Schnittstelle ist nicht öffentlich und nicht Open Source! Sie benötigen die offizielle DATEV-Dokumentation, um Informationen darüber zu erhalten, wie die CSV- und XML-Dateien gestaltet sein müssen.

#### XML Data Source

The xml data source is generated by the set of selected invoices defined by report definition and the DATEV export workitem itself. So the number of data entries is the count of invoices +1.
DATEVasdfDDD
To identify the type of document you can make use of the xsl select statement:
Die XML-Datenquelle wird aus der Liste der ausgewählten Belege erzeugt, die durch die Report Schnittstelle definiert sind, und dem DATEV-Export-Workitem selbst generiert. Die Anzahl der Dateneinträge entspricht damit der Anzahl der Belege+1.

Um den Dokumenttyp zu identifizieren, können Sie die entsprechenden xsl select-Anweisung verwenden:

```xml
....
<xsl:template
match="/data/document[normalize-space(item[@name = '$workflowgroup']/value) = 'DATEV-Export']">
Expand All @@ -92,14 +114,15 @@ To identify the type of document you can make use of the xsl select statement:
....
</xsl:template>
.....
```

## Forms
## Formular

There are also custom form Elements that can be used for typical Datev processes
Es gibt auch benutzerdefinierte Formularelemente, die für typische Datev-Prozesse verwendet werden können

### Booking Table

The custom form section `datev/booking_account` can be used to display a booking table
Über die custom form-section `datev/booking_account` kann ein Formularbereich für eine Buchungstabelle angezeigt werden

```
<imixs-form-section type="custom" path="datev/booking_account" label="Buchungen" />
Expand All @@ -109,7 +132,7 @@ The custom form section `datev/booking_account` can be used to display a booking

### Search Konto

The custom form part `datev/account_search` can be used to display a input search field for debitor / creditor accounts
Über das custom form part `datev/account_search` kann ein Eingabesuchfeld für Debitoren-/Kreditorenkonten angezeigt werden.

```xml
<item name="datev.cdtr" type="custom"
Expand All @@ -120,8 +143,8 @@ The custom form part `datev/account_search` can be used to display a input searc

<img src="image-02.png" />

You can restrict the search result optional by providing a regular expression.
For example, if you want to filter only account numbers that start with "7", you can add a regex as follows:
Sie können das Suchergebnis optional einschränken, indem Sie einen regulären Ausdruck über das Attribut 'options' angeben.
Wenn Sie z. B. nur Kontonummern filtern möchten, die mit "7" beginnen, können Sie einen regulären Ausdruck wie folgt hinzufügen:

```xml
<item name="datev.cdtr" type="custom"
Expand All @@ -131,18 +154,20 @@ For example, if you want to filter only account numbers that start with "7", you
required="false" />
```

This filters all account numbers that start with "7". The ^ anchor characters in the regex mean that the string must start with "7", and .\* means that after the "7" any character can follow.
Durch diesen Filter werden alle Kontonummern gefiltert, die mit "7" beginnen. Die ^ Ankerzeichen im regulären Ausdruck bedeuten, dass der String mit "7" beginnen muss, und .\* bedeutet, dass nach der "7" ein beliebiges Zeichen folgen kann.

## Maven

The imxis-adapter-sepa module can be added into an applicaton module. The module provides CDI and EJB components. Optional the module contains also JSF pages to be used for frontends.
Das Modul imxis-adapter-datev kann in jedes Maven Projekt eingefügt werden. Das Modul stellt CDI- und EJB-Komponenten zur Verfügung. Optional enthält das Modul auch JSF-Seiten, die für Frontends verwendet werden können.

Add the following maven dependency into a parent project:
Fügen Sie die folgende Maven-Abhängigkeit zu einem übergeordneten Projekt hinzu:

```xml
<!-- DATEV Adapter -->
<dependency>
<groupId>org.imixs.workflow</groupId>
<artifactId>imixs-adapters-datev</artifactId>
<version>${org.imixs.adapters.version}</version>
<scope>provided</scope>
</dependency>
```
28 changes: 7 additions & 21 deletions imixs-adapters-datev/src/reports/datev_csv_invoices.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,28 +103,14 @@
<xsl:template
match="/data/document[normalize-space(item[@name = '$workflowgroup']/value) != 'DATEV-Export']">

<!-- compute invoice date: if invoice.accounting.date not defined, then the fallback is
invoice.date -->
<xsl:variable
name="date">
<xsl:choose>
<xsl:when test="string-length(item[@name='invoice.accounting.date']/value) = 0">
<!-- Fallback... -->
<xsl:value-of
select="item[@name='invoice.date']/value" />
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="item[@name='invoice.accounting.date']/value" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>

name="belegdatum" select="item[@name='datev.belegdatum']/value" />
<xsl:variable
name="gegenkonto" select="item[@name='datev.gegenkonto']/value" />
name="belegfeld1" select="item[@name='datev.belegfeld1']/value" />
<xsl:variable
name="subject" select="substring(item[@name='$workflowsummary']/value,1,59)" />
name="gegenkonto" select="item[@name='datev.gegenkonto']/value" />
<xsl:variable
name="invoicenumber" select="item[@name='invoice.number']/value" />
name="buchungstext" select="substring(item[@name='$workflowsummary']/value,1,59)" />
<xsl:variable
name="uniqueid" select="item[@name='$uniqueid']/value" />
<xsl:for-each
Expand All @@ -151,12 +137,12 @@
<xsl:value-of
select="./item[@name='datev.buschluessel']/value" /><xsl:text>;</xsl:text>
<xsl:value-of
select="format-dateTime($date, '[D01][M01]')" /><xsl:text>;</xsl:text>
select="format-dateTime($belegdatum, '[D01][M01]')" /><xsl:text>;</xsl:text>
<xsl:value-of
select="$invoicenumber" /><xsl:text>;</xsl:text>
select="$belegfeld1" /><xsl:text>;</xsl:text>
<xsl:text>;;</xsl:text>
<xsl:value-of
select="$subject" /><xsl:text>;</xsl:text>
select="$buchungstext" /><xsl:text>;</xsl:text>
<xsl:text>;;;;;</xsl:text>

<!-- Beleglink -->
Expand Down

0 comments on commit d074e04

Please sign in to comment.