OmniBelegService:KonfigurationPDFExport: Unterschied zwischen den Versionen

(4 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)

Zeile 1:

~~folgt~~

== Vorwort ==

Mit dem PDF-Export erstellt der OmniBelegService automatisch Rechnungs-PDFs aus vorhandenen Sage-Verkaufsbelegen und legt diese in einem konfigurierbaren Verzeichnis ab. Die Auswahl der Belege erfolgt über eine Prüfprozedur in der Datenbank.

Es können mehrere Exportformate angelegt werden, beispielsweise für unterschiedliche Mandanten oder Verkaufskanäle. Jedes Format besitzt eine eigene Belegauswahl, einen Exportpfad, ein Dateinamensmuster und eine Berichtskonfiguration.

Der PDF-Export arbeitet unabhängig vom Belegimport. Es können auch Belege verarbeitet werden, die direkt in Sage oder durch andere Anwendungen angelegt wurden, sofern diese die Auswahlbedingungen erfüllen.

Die Konfiguration befindet sich im Bereich '''PDF-Export'''. Die Einstellungen eines Formats sind auf die Reiter '''Allgemein''', '''Regelwerk''', '''PDF-Ablage''' und '''Sage-Bericht''' verteilt.

== Voraussetzungen ==

* Der OmniBelegService ist eingerichtet und der Dienst läuft.

* Die PDF-Exportfunktion ist lizenziert und der PDF-Exportjob ist in der Dienststeuerung aktiviert.

* Die erforderlichen Datenbanktabellen und die Prüfprozedur wurden über das Setup installiert.

* Der konfigurierte Sage-Benutzer kann den gewünschten Bericht für den angegebenen Mandanten ausführen.

* Das Windows-Konto des Dienstes besitzt Schreibzugriff auf das Exportverzeichnis.

== Exportformate verwalten ==

In der Liste auf der linken Seite wird das gewünschte Exportformat ausgewählt. Rechts erscheinen dessen Einstellungen.

{| class="wikitable"

! Schaltfläche !! Beschreibung

|-

| Neues Exportformat || Legt ein neues, zunächst inaktives Exportformat an.

|-

| Format kopieren || Kopiert das ausgewählte Format mit seinen Einstellungen. Die Kopie erhält eine eigene ID beim Speichern und ist zunächst inaktiv.

|-

| Format löschen || Entfernt das ausgewählte Format aus der Konfiguration. Die Löschung wird erst durch Speichern übernommen. Bisherige Exportprotokolle bleiben erhalten.

|-

| Speichern || Prüft und speichert die geänderten Exportformate und übernimmt vorgemerkte Löschungen. Im PDF-Exportbereich kann auch '''Strg+S''' verwendet werden.

|-

| Änderungen verwerfen || Lädt den zuletzt gespeicherten Stand erneut. Ungespeicherte Änderungen werden verworfen.

|-

| Exportordner auswählen || Öffnet eine Ordnerauswahl und übernimmt den gewählten Pfad in das ausgewählte Format. Anschließend speichern.

|}

Die Hintergrundfarbe eines Listeneintrags zeigt den Zustand des Formats: '''Grün''' bedeutet aktiv, '''Rot''' bedeutet inaktiv. Ungespeicherte Änderungen werden durch eine gelb-orange Schriftfarbe gekennzeichnet.

Gespeicherte Änderungen übernimmt der Dienst über seinen regelmäßigen Hintergrundabgleich. Ein Dienstneustart ist dafür nicht erforderlich. Die Übernahme erfolgt abhängig von den eingestellten Intervallen; ein bereits gestarteter PDF-Druck wird noch abgeschlossen.

[[Datei:Uebersicht PDFExportConfig.png|alternativtext=Uebersicht_PDFExportConfig|1200x1200px]]

== Allgemein ==

{| class="wikitable"

! Bezeichnung !! Beschreibung und Werte

|-

| Aktiv || Legt fest, ob das Exportformat verarbeitet wird. Zusätzlich müssen die PDF-Lizenz und der globale PDF-Exportjob aktiviert sein. Neue und kopierte Formate sind zunächst inaktiv.

|-

| ID || Interne Kennung des Exportformats. Sie wird beim erstmaligen Speichern vergeben und ist nicht editierbar. Der Exportstatus wird für jedes Format getrennt geführt.

|-

| Mandant || Nummer des Sage-Mandanten, dessen Belege exportiert werden sollen. Hier wird eine positive Mandantennummer eingetragen.

|-

| Name || Frei wählbarer Name des Exportformats. Dieser wird in der Formatliste und in der Protokollierung verwendet. Empfehlenswert ist eine eindeutige Bezeichnung, beispielsweise <code>Rechnungen Webshop DE</code>.

|}

== Regelwerk ==

=== Belegauswahl ===

{| class="wikitable"

! Bezeichnung !! Beschreibung und Werte

|-

| OrderChannel || Verkaufskanal, auf den die Auswahl eingeschränkt werden soll. Die mitgelieferte Prüfprozedur vergleicht den Wert mit <code>USER_OrderChannel</code> im Belegkopf. Ein leerer Wert berücksichtigt alle Verkaufskanäle. Pro Format wird ein Kanal angegeben; für getrennte Ablagen können mehrere Formate angelegt werden.

|-

| Belegkennzeichen (Komma/Semikolon) || Belegarten, die berücksichtigt werden sollen. Mehrere Kennzeichen können durch Komma oder Semikolon getrennt werden, beispielsweise <code>VFR, VSD; VSL</code>. Standardmäßig sind <code>VFR,VSD,VSL</code> vorbelegt. Weitere oder kundenspezifische Kennzeichen können entsprechend der Sage-Einrichtung eingetragen werden.

|}

=== Prozedur ===

{| class="wikitable"

! Bezeichnung !! Beschreibung und Werte

|-

| Prüfprozedur || Name der SQL-Prozedur, die die zu exportierenden Belege ermittelt. Standardwert: <code>spOmniBelegServiceInvoiceCheck</code>. Bei kundenspezifischen Anforderungen kann eine andere, entsprechend vorbereitete Prozedur hinterlegt werden, optional mit Schema, beispielsweise <code>dbo.spKundenInvoiceCheck</code>.

|}

Die Prüfprozedur erhält Mandant, OrderChannel, Belegkennzeichen und Exportformat-ID. Sie bestimmt die tatsächliche Belegauswahl. Bei kundenspezifischen Prozeduren hängt die Berücksichtigung der Filter von deren Umsetzung ab.

Die aktuell mitgelieferte Standardprozedur berücksichtigt passende Verkaufsbelege der letzten '''30 Tage'''. Bereits erfolgreich exportierte Belege und Belege mit fünf abgeschlossenen oder begonnenen Exportversuchen werden ausgeschlossen.

Die Standardprozedur kann durch zukünftige Updates aktualisiert werden. Für kundenspezifische Anpassungen kopieren Sie die Prozedur unter einem eigenen Namen und hinterlegen diesen im Feld „Prüfprozedur“ des Exportformats. Änderungen sollten nicht direkt an der Standardprozedur vorgenommen werden, da sie bei einem Update überschrieben werden könnten.

== PDF-Ablage ==

=== Ablage ===

{| class="wikitable"

! Bezeichnung !! Beschreibung und Werte

|-

| Exportpfad || Absoluter Zielpfad für die erzeugten PDF-Dateien, beispielsweise <code>D:\PDF-Export\Webshop</code> oder <code>\\Dateiserver\Rechnungen\Webshop</code>. Der Pfad wird aus Sicht des Dienstrechners verwendet. Das Dienstkonto benötigt die entsprechenden Schreibrechte. Der Ordner wird bei Bedarf angelegt. Platzhalter im Exportpfad werden nicht aufgelöst.

|-

| Dateinamensmuster || Aufbau des PDF-Dateinamens. Es können fester Text und die unten aufgeführten Platzhalter kombiniert werden. Standardwert: <code>Rechnung_{Belegjahr}_{Belegnummer}_{BelID}.pdf</code>. Die Endung <code>.pdf</code> wird ergänzt, wenn sie fehlt.

|}

Bei Netzwerkpfaden empfiehlt sich ein UNC-Pfad. Laufwerkszuordnungen des angemeldeten Benutzers stehen einem Windows-Dienst üblicherweise nicht zur Verfügung.

=== Platzhalter für den Dateinamen ===

{| class="wikitable"

! Platzhalter !! Beschreibung / Datenquelle

|-

| <code>{Belegnummer}</code> || Belegnummer des Verkaufsbelegs.

|-

| <code>{Belegjahr}</code> || Belegjahr des Verkaufsbelegs.

|-

| <code>{ShopOrderID}</code> || Externe Bestellnummer aus <code>USER_ShopOrderID</code> im Belegkopf.

|-

| <code>{BelID}</code> || Interne Sage-Beleg-ID.

|-

| <code>{OrderChannel}</code> || Verkaufskanal aus <code>USER_OrderChannel</code> im Belegkopf.

|-

| <code>{Referenznummer}</code> || Referenznummer aus dem Belegkopf.

|}

Die Groß-/Kleinschreibung der Platzhalter spielt keine Rolle. Fehlende Textwerte ergeben einen leeren Bestandteil im Dateinamen. Unzulässige Windows-Dateinamenzeichen innerhalb der Belegwerte werden durch einen Unterstrich ersetzt. Das Muster selbst darf keine Verzeichnisse enthalten.

Beispiel:

<pre>Rechnung_{Belegjahr}_{Belegnummer}_{BelID}.pdf

→ Rechnung_2026_4711_12345.pdf</pre>

'''Hinweis:''' Der Dateiname sollte im Zielverzeichnis eindeutig sein. Ein vorhandenes PDF mit demselben Namen wird nach erfolgreicher Erstellung der neuen PDF ersetzt. Dies gilt auch dann, wenn unterschiedliche Belege oder Exportformate denselben Dateinamen erzeugen. Die interne BelID im Muster und getrennte Ordner je Mandant helfen, Namensüberschneidungen zu vermeiden.

== Sage-Bericht ==

=== Bericht ===

{| class="wikitable"

! Bezeichnung !! Beschreibung und Werte

|-

| Berichtname || Technischer Name des Sage-Berichts, der für die PDF-Erstellung verwendet wird. Standardwert: <code>rptVKRechnung</code>.

|-

| Partnerkennung || Partnerkennung des Berichts in Sage. Standardwert: <code>Sage</code>. Bei individuell bereitgestellten Berichten kann eine abweichende Kennung erforderlich sein.

|-

| Lösung || Lösungskennung des Berichts in Sage. Standardwert: <code>Wawi</code>. Bei individuellen Berichten ist die dazugehörige Lösungskennung einzutragen.

|}

Die drei Angaben identifizieren gemeinsam den zu verwendenden Bericht. Mit den Standardwerten lautet die Berichtskennung <code>rptVKRechnung.Sage.Wawi</code>. Hier werden technische Berichtskennungen eingetragen, keine Lizenznummern oder Windows-Benutzerdaten.

Der Export verwendet den im OmniBelegService konfigurierten Sage-Benutzer. Die Angaben zur Berichtsauswahl werden ausdrücklich übergeben und müssen deshalb auch bei bestehender Sage-Anmeldung hinterlegt sein. Für den Standardbericht können die vorbelegten Werte verwendet werden.

=== Sprache ===

{| class="wikitable"

! Bezeichnung !! Beschreibung und Werte

|-

| Standardsprache || Ersatzsprache, wenn im Beleg keine Sprache hinterlegt ist. Standardwert: <code>DE</code>. Ist am Beleg eine Sprache vorhanden, wird diese verwendet. Der gewählte Bericht muss die gewünschte Sprache unterstützen.

|}

== Beispiel: Rechnungen eines Webshops exportieren ==

# Im Bereich '''PDF-Export''' auf '''Neues Exportformat''' klicken.

# Unter '''Allgemein''' den Namen <code>Rechnungen Webshop DE</code> und den gewünschten Mandanten, beispielsweise <code>1</code>, eintragen.

# Unter '''Regelwerk''' den tatsächlich am Beleg hinterlegten OrderChannel, beispielsweise <code>Webshop-DE</code>, eintragen. Die Belegkennzeichen auf <code>VFR,VSD,VSL</code> setzen. Die Standardprüfprozedur beibehalten, sofern keine kundenspezifische Auswahl vorgesehen ist.

# Unter '''PDF-Ablage''' beispielsweise <code>\\Dateiserver\Rechnungen\Webshop-DE</code> und das Muster <code>Rechnung_{Belegjahr}_{Belegnummer}_{BelID}.pdf</code> hinterlegen.

# Unter '''Sage-Bericht''' für den Standardbericht die Werte <code>rptVKRechnung</code>, <code>Sage</code> und <code>Wawi</code> beibehalten.

# Das Format unter '''Allgemein''' aktivieren und '''Speichern''' wählen.

# Nach dem nächsten Exportlauf die erzeugten Dateien und das Protokoll kontrollieren.

== Exportverhalten und Fehler ==

Der PDF-Export läuft als eigener Job im konfigurierten Dienstintervall. Erfolgreiche Exporte werden je '''Mandant, BelID und Exportformat-ID''' gespeichert und in weiteren Durchläufen nicht erneut ausgeführt. Eine nachträgliche Änderung des Dateinamensmusters oder des Exportpfads löst keinen erneuten Export bereits erfolgreicher Belege aus.

Ein Beleg kann über mehrere Exportformate ausgegeben werden, wenn er deren jeweilige Auswahlbedingungen erfüllt. Die Verarbeitung und die Exportversuche werden pro Format getrennt geführt.

Bei einem fehlgeschlagenen Export wird der Beleg in späteren Durchläufen erneut versucht, sofern er weiterhin in die Belegauswahl fällt. Es erfolgen maximal '''fünf Versuche insgesamt'''. Auch ein beim Dienstabbruch bereits begonnener Versuch zählt mit. Nach Erreichen der Grenze ist eine gezielte Prüfung und gegebenenfalls ein Zurücksetzen des Status durch den betreuenden Administrator erforderlich.

Fehler werden im Protokollbereich '''InvoiceExport''' mit Fehlernummern von '''400 bis 410''' dokumentiert. Die technische Meldung enthält weitere Angaben zur Ursache. Bei einer ausgeschalteten oder nicht lizenzierten PDF-Funktion werden keine Exportversuche gestartet.

Ein vorhandenes PDF wird erst ersetzt, nachdem die neue PDF erfolgreich erstellt und geprüft wurde. Scheitert die Erstellung, bleibt die vorhandene Datei erhalten.

[[OmniBelegService:Handbuch|Zurück zum Handbuch]]

MH (Diskussion | Beiträge)