1 Themenübersicht
Mit der Hook-Contract-Definition „Belegkette“ werden Schnittstellen bereitgestellt, mit denen die Belegkette durch Apps erweitert werden kann.
Die Belegketten der Standard-Belegtypen verwenden diese Hook-Contract-Definition. Sie können daher die Implementierungen im Standard als Beispiel-Implementierungen heranziehen.
In dieser Dokumentation ist beschrieben, welche Erweiterungen Sie mit der Hook-Contract-Definition vornehmen können und welche Einschränkungen und Besonderheiten Sie beachten müssen.
Eine Schnittstellenbeschreibung finden Sie im zugehörigen Entwicklungsobjekt vom Typ „Hook Contract“. Ausführliche Informationen zu den in den Schnittstellen deklarierten Methoden finden Sie in den zugehörigen Java-Klassen.
Informationen zur Hook-Infrastruktur finden Sie in der Dokumentation „Hook Contracts“.
2 Zielgruppe
- Entwickler
3 Beschreibung
Mit der Hook-Contract-Definition „Belegkette“ sind folgende Erweiterungen möglich:
- Registrierung von Belegtypen als Quell-/Zielkombination eines Belegketteneintrags
- Berücksichtigung der Quell- und Zielbelege bei der Reorganisation von Beleginstanzen
- Markierung eines Belegketteneintrages als intern (in Abhängigkeit zu einer gegebenen Belegbasis oder -position der aktuellen Anwendung)
- Bereitstellung von Informationen, die zur Darstellung der Belegketteneinträge eines Belegtyps benötigt werden
- Beeinflussung der Sortierung innerhalb der Belegkette
- Definition des GUI-Elements für einen Belegtyp
Hook-Contract-Definition:
com.cisag.app.general.order.hook.OrderReference
Als eine Beispiel-Implementierung für die Registrierung der Quell-/Ziel-Belegtypenkombinationen für die Belegkette im Standard dient die folgende Hook-Contract-Implementierung, welche alle Registrierungen für das Framework „Vertrieb“ enthält:
com.cisag.app.sales.order.OrderReferenceSalesImpl
Als eine Beispiel-Implementierung für die Markierung von Belegketteneinträgen als intern kann die folgende Standard-Hook-Contract-Implementierung dienen:
com.cisag.app.general.order.InternalOrderReference
Als eine Beispiel-Implementierung für die Darstellung der Belegkette im Standard kann die folgende Hook-Contract-Implementierung für den Belegtyp „Vertriebsauftrag“ dienen:
com.cisag.app.sales.order.OrderReferenceSalesOrderImpl
3.1 Besonderheiten
3.1.1 Registrierung
Durch die Implementierung des folgenden Hook-Interface können neue Kombinationen von Belegtypen für die Unterstützung in der Belegkette registriert werden. Hierfür müssen jeweils ein Quell- und ein Zielbelegtyp angegeben werden.
com.cisag.app.general.order.hook.log.OrderReferenceRegistrationHook
Hinweis:
Wie Sie in einer App einen neuen Belegtyp hinzufügen können, lesen Sie in diesem Dokument: Hook-Contract-Definition: Belegtyp
Für eine Implementierung im Standard, d. h. mit dem Entwicklungspräfix „cisag“, müssen sowohl Quell- als auch Zielbeleg aus dem Standard stammen.
Für die Implementierung in einer App muss eine der folgenden Voraussetzungen erfüllt sein:
- Quell- und Zielbelegtyp gehören zur selben App
- einer der beiden Belegtypen gehört gemäß Entwicklungspräfix zu der App, der andere ist ein Standard-Belegtyp
Nicht erlaubt sind demnach z. B. Kombinationen aus verschiedenen Apps. Dies gilt auch dann, wenn sie dasselbe Entwicklungspräfix haben. Ebenso ist es nicht möglich in einer App Kombinationen zu registrieren, bei denen sowohl Quell- als auch Zielbeleg aus dem Standard stammen.
Reorganisation
Mithilfe der folgenden Methode legen Sie fest, ob ein Beleg reorganisiert werden darf, der zu einer für die Belegkette registrierten Quell- oder Zielbelegtypkombination gehört:
OrderReferenceRegistry.registerOrderReference(short, short, ReorganizationRule)
Wenn Sie für die Methode keinen Wert angeben, dann gilt folgende Regel für die Belege der registrierten Kombination:
- Ein Beleg des Quellbelegtyps kann nicht reorganisiert werden, wenn ein Beleg des Zielbelegtyps vorhanden ist.
- Ein Beleg des Zielbelegtyps kann nicht reorganisiert werden, wenn ein Beleg des Quellbelegtyps vorhanden ist.
Die Erläuterungen zu den weiteren möglichen Werten für die Methode finden Sie in der Java-Klasse des Hook-Interface OrderReferenceRegistrationHook.
Darüber hinaus können Sie mit dem folgenden Hook-Interface Prüfungen für die Belegreorganisation hinzufügen:
com.cisag.app.general.order.hook.log.ReorganizationValidateHook
Hinweis:
Sie können bspw. per ReorganizationRule die Reorganisationsprüfungen entfernen und mit dem Hook-Interface ReorganizationValidateHook eigene Prüfungen für die Reorganisation hinzufügen.
3.1.2 Ausblenden von internen Einträgen
Normalerweise werden für eine gegebene Belegbasis oder Belegposition alle zugehörigen Belegketteneinträge angezeigt. Durch die Implementierung des folgenden Hook-Interfaces kann aber ein vorhandener Belegketteneintrag unter Berücksichtigung der gegebenen Belegbasis oder Belegposition als intern markiert werden, so dass dieser nicht mehr angezeigt wird.
com.cisag.app.general.order.hook.log.InternalOrderReferenceHook
3.1.3 Sortierung
Die Sortierung der Belegkette kann durch die Implementierung des folgenden Hook-Interfaces bestimmt werden: com.cisag.app.general.order.hook.log.OrderReferenceComparatorHook
Mit der Methode getOrderType wird bestimmt, um welchen Belegtyp es sich handelt und mit der Methode getPreviousOrderType wird der Vorgängerbelegtyp festgelegt. In den folgenden Grafiken deuten die Pfeile jeweils den gesetzten Wert für previous an. Hier handelt es sich nur um die Reihenfolge in der Sortierung und kann theoretisch völlig unabhängig vom Prozessablauf definiert werden.
Hinweis:
Die Grafiken dienen nur zur Verdeutlichung des Prinzips und entsprechen nicht den echten Registrierungen.
Das Angebot hat keinen Vorgänger, der Auftrag hat das Angebot als Vorgänger. Der berechnete Sortierwert ist somit für das Angebot „1“ und für den Auftrag „2“.
Hier haben sowohl das Angebot als auch der Kontrakt keinen Vorgänger. Beide erhalten den Sortierwert „1“, während der Auftrag wieder den Sortierwert „2“ erhält. In diesem Fall erhält der Beleg mit dem kleineren Wert für OrderType den Vorzug.
Die Registrierungen im Standard erhalten hinsichtlich der Sortierung immer den Wert „Level 1“. Registrierungen in einer App erhalten den Wert „Level 2“, so dass es per App möglich ist eine Einsortierung zwischen bestehenden Standard-Belegtypen zu erreichen.
Im ersten Schritt wird der jeweilige Sortierwert der Standardbelege berechnet, hier für das Angebot „1“ und für den Auftrag „2“. Belege, die einen App-Belegtyp als Vorgänger haben, erhalten dessen Sortierwert erhöht in der zweiten Stelle. Belege, die einen Standardbeleg als Vorgänger haben, erhalten in der ersten Stelle den Sortierwert ihres Standardvorgängerbelegs und in der zweiten Stelle den Wert „1“. Wie auch im Standard kann es auch mehrere App-Belegtypen geben, die den gleichen Sortierwert haben.
Die Sortierung erfolgt dann zuerst nach der ersten Stelle des Sortierwertes. Sollte dieser gleich sein, kommt die zweite Stelle zum Tragen. Sollte auch dann keine Reihenfolge feststehen, erhält auch hier der Beleg mit dem kleineren Wert für OrderType den Vorzug.
Im angezeigten Beispiel ergibt sich folgende Sortierreihenfolge:
AppBelegA, Angebot, AppBelegB, AppBelegC, Auftrag, AppBelegD
Hinweis:
Sofern zukünftig können Apps andere Apps voraussetzen. Die Sortierlogik wird in diesem Fall einfach um eine weitere Stelle erweitert (d.h. Sortierwerte wie z.B. „1.2.1“ entstehen.)
3.1.4 Datenbereitstellung
Die Darstellung der Belegketteneinträge erfolgt entweder auf Ebene der Belegbasis, oder – sofern der Belegtyp Positionen unterstützt – auf Positionsebene. Sie basiert auf Instanzen von
com.cisag.app.general.order.hook.log.OrderReferenceData.
Durch die Implementierung der folgenden Hook-Interfaces ist es möglich, die Objektdaten in OrderReferenceData-Instanzen umzuwandeln. Diese enthalten Daten, die typischerweise jeder Beleg hat (Datum, Belegpartner, Artikel etc.), oder spezifische Daten, die nur zu dem jeweiligen Belegtyp gehören.
Für die Bereitstellung der Basis- und der optionalen Positionsdaten dienen die folgenden Hook-Interfaces:
com.cisag.app.general.order.hook.log.OrderReferenceHeaderDataHook
com.cisag.app.general.order.hook.log.OrderReferenceDetailDataHook
3.1.5 GUI-Darstellung eines Belegketteneintrages
Die eigentliche Darstellung des Belegketteneintrags erfolgt durch die Implementierung des Hook-Interfaces
com.cisag.app.general.order.hook.ui.OrderReferenceRendererHook
Die folgende Klasse wird im Standard bereitgestellt und ist die Basis für die Implementierungen im Standard. Jedoch ist auch eine völlig eigenständige Implementierung möglich.
com.cisag.app.general.order.hook.ui. DefaultOrderReferenceRenderer