Individualisierung 4SELLERS ELEMENTS

In ELEMENTS könnten im Administrationsbereich Aktionen angelegt werden. Damit bist du in der Lage, ELEMENTS um individuelle Anpassungen zu erweitern.

Unter „Aktionen” kannst du beliebig viele Aktionen anlegen, die dann entweder als Eintrag im Kontext- oder Drei Punkte-Menü erscheinen, automatisch ausgeführt werden oder dem Benutzer auf der Oberfläche angezeigt werden.

Du möchtest, dass unter bestimmten Bedingungen eine Sofortrechnung – also die Kombination aus Lieferschein und Rechnung – aus ELEMENTS heraus erstellt werden kann, da ihr ein Ladengeschäft habt. Der Benutzer soll dazu im Kontext- oder Drei Punkte-Menü der Bestellung einfach den Eintrag „Mitnahmedokumente erstellen” und es wird eine Sofortrechnung in ELEMENTS erzeugt und als Druckvorschau angezeigt.

BEISPIEL

Die Logik, die beim Auslösen der Aktion in ELEMENTS durchlaufen werden muss, befindet sich ausschließlich im Sage Application Server. Bitte wende dich an deinen ERP-Partner, damit er diese Logik in den Sage Application Server einbinden kann.

HINWEIS

Grundlagen

Einstellungen für alle Aktionen

Folgende Angaben musst du bei allen Aktionen vornehmen:

Aktiv

Sobald du eine Aktion aktivierst, wird diese in ELEMENTS sichtbar.

Bezeichnung

Benenne die Aktion so, dass der Benutzer weiß, welchen Schritt er damit auslöst. Dies ist insbesondere wichtig, wenn er über ein Kontext- oder Drei Punkte-Menü darauf zugreifen kann. Mit Hilfe einer eindeutigen und selbsterklärenden Bezeichnung weiß der Benutzer, welches Ergebnis er durch das Anklicken des Eintrags erwarten kann.

Nenne deine Aktion lieber „Rücklieferschein erstellen” als „Rücklieferschein”.

TIPP

Aktionstyp

Du kannst eine Aktion genau einem Aktionstyp zuordnen. Der Aktionstyp legt fest, welche Einstiegspunkte für die automatische Ausführung zur Verfügung stehen und ob die Aktion auch im Kontext- oder Drei Punkte-Menü der Entität zur Verfügung steht.

Nach dem Speichern kannst du den Aktionstyp nicht mehr ändern.

HINWEIS

Entität

Je nach Aktion kannst du auswählen, in welcher Entität diese aktiviert wird. Möchtest du eine Aktion in verschiedenen Entitäten mit einer anderen Logik versehen, so kannst du diese einfach ein weiteres Mal anlegen und die Aktionen jeweils anderen Entitäten zuordnen.

Endpunkttyp

Lege den Endpunkttyp der Aktion fest. Aktuell kann lediglich eine Aktion auf dem Sage Appserver ausgelöst werden. Eine Erweiterung auf andere Aktionstypen ist angedacht.

Für den Endpunkttyp Sage Appserver sind zwei weitere Felder Pflicht:

Aktion
Gib hier bitte den Namen der Klasse ein, die die Implementierung der Aktion beinhaltet, inklusive kompletten Namespace. (z.B. „Custom.Action.TestAction“)

DLL_Datei
Trage bitte den Namen der dll-Datei ein, die auf dem von ELEMENTS genutzten Application Server im Shared-Verzeichnis der Sage100 liegt. (z.B. „Custom.Action.dll“)

Einschränkung der Aktionen auf Benutzer- oder Business-Login-Gruppen

Du kannst bei jeder Aktion festlegen, ob diese allen Benutzer- oder Business-Login-Gruppen zur Verfügung steht oder nicht. Selbstverständlich kannst du das auch auf Gruppen eingrenzen. Wenn du in einer der Karten „Gültig für“ den Eintrag „Alle Benutzergruppen“ oder „Alle Business-Login-Gruppen“ aktivierst, haben alle Benutzer und Business-Logins Zugriff auf die Aktion. Das bedeutet, dass sie alle die Aktion manuell ausführen können oder diese automatisch ausgeführt wird.

Deaktivierst du die Funktion, so wird dir eine Tabelle angezeigt. Dort kannst du dann individuell entscheiden, welche Benutzer- oder Business-Login-Gruppe diese Aktion manuell ausführen darf bzw. diese automatisch ausgeführt wird.

Wenn du eine Aktion anlegst, so wird diese automatisch allen Benutzergruppen freigegeben. Für Business-Login-Gruppen musst du die Freigabe bitte selbst vornehmen. Hier wird standardisiert keine Freigabe erteilt.

Ist ein Benutzer oder ein Business-Login Mitglied in mehreren Gruppen, so musst du allen Gruppen die Berechtigung entziehen, in denen der Benutzer oder ein Business-Login Mitglied ist.

HINWEIS

Die unter der Aktion angegebene Klasse muss eine Methode mit folgender Signatur aufweisen:

public Dictionary<string,object> Execute(Dictionary<string, object> parameter)

Allgemeine Eingabeparameter

Alle Parameter für die Aktion werden im Methoden-Parameter übergeben. Folgende Parameter stehen immer zur Verfügung:

KeyDatentypValue
ClientSagede.OfficeLine.Engine.Mandantdas Mandanten-Objekt
CultureIdstringdie ID der beim ELEMENTS-Benutzer hinterlegten Lokalisierung / Oberflächensprache
Automaticbooldas Kennzeichen, das angibt, ob die Aktion automatisch ausgeführt wird
ErpUserstringder Name des beim ELEMENTS-Benutzer hinterlegten ERP-Benutzers
LocationKeystringder technische Schlüssel des Standortes, den der ELEMENTS-Benutzer aktuell verwendet

In einigen Aktionen stehen auch Positionsdaten zur Verfügung. Das sind immer folgende Daten:

KeyDatentypValue
EntityKeystringder ELEMENTS-Key für diesen Datensatz
ItemNumberstringdie Artikelnummer
VariationIdintdie interne Variantennummer (AuspraegungID)
Quantitydecimaldie Menge
QuantityTypeshortdie Mengenart
QuantityUnitstringdie Mengeneinheit
UnitPricedecimalder Einzelpreis
DiscountValuedecimalder Rabattsatz (in Prozent)
IsManualPricebooldas Kennzeichen, ob der Einzelpreis manuell verändert worden ist (EinzelpreisManuell)
ExternalEntityReferencestringdie ELEMENTS-Referenz zur Position, bei ans ERP übergebenen Positionen die BelPosId

Wenn in einer Aktion zusätzliche Daten übergeben werden, ist das in der Aktion selbst beschrieben.

HINWEIS

Entity-Spezifische Eingabeparameter

Folgende Parameter stehen für die jeweilige Entität immer zur Verfügung:

KeyDatentypValueEntitäten
ExternalEntityReferencestringDie ELEMENTS-Referenznummer für diese Entität
Das Format ist abhängig von der Konfiguration in den ELEMENTS-Einstellungen
(z.B. DFFC4C71-63E5-4625-83DC-FD937DB3F7C1)
Bestellung,
Angebot,
Warenkorb

Allgemeine Ausgabeparameter

Folgende Ausgabeparameter werden immer interpretiert:

KeyDatentypValue
Messagestring, string[]die anzuzeigende Meldung bzw. Meldungen für mehrere Zeilen
MessageTypestringDer Typ der Meldung. Dieser wird ignoriert, wenn der Parameter Message nicht angegeben ist. Folgende Werte werden unterstützt:
Information: Meldung wird als Information dargestellt
Warning: Meldung wird als Warnung dargestellt
Error: Meldung wird als Fehler dargestellt
Ist kein Wert oder ein ungültiger Wert angegeben, so wird Information verwendet.
MessageCaptionstringeine Überschrift für die Message
HtmlDictionary<string,object>enthält die Daten für das Anzeigen einer HTML-Meldung im Modal
FilesDictionary<string,object>ein Array von Datei-Definitionen

Das können die Inhalte der HTML-Meldung sein:

KeyDatentypValue
Contentstringdie HTML Meldung
Height (optional)intdie Höhe des Bereichs, in welchem die Meldung angezeigt wird
Width (optional)intdie Weite des Bereichs, in welchem die Meldung angezeigt wird

Das können die Inhalte der Dateien sein:

KeyDatentypValue
FileNamestringder Dateiname zur Anzeige und zur Ermittlung des Dateityps
FileContentstringder Base64 kodierte Dateiinhalt

Die Darstellung von Dateien kann nicht von allen Aktionen unterstützt werden. Bitte beachte den entsprechenden Hinweis an der jeweiligen Aktion.

HINWEIS

Alle zusätzlichen Einträge im Ergebnis werden ignoriert.

Beispiel

using System.Collections.Generic;
namespace Custom.TestAssembly
{
    public class ExampleAction
    {
        public Dictionary<string,object> Execute(Dictionary<string, object> parameter)
        {
            var client = parameter.TryGetValue("Client", out var clientObj) ? clientObj as Mandant : null;
            var documentId = parameter.TryGetValue("DocumentId", out var documentIdObj) && int.TryParse(documentIdObj?.ToString(), out var documentIdParsed) ? documentIdParsed : (int?)null;
            var automatic = parameter.TryGetValue("Automatic", out var automaticObj) && automaticObj != null ? (bool)automaticObj : false;
            var cultureId = parameter.TryGetValue("CultureId", out var cultureIdObj) && cultureIdObj != null ? cultureIdObj?.ToString() : "de-DE (Fallback)";
            var erpUser = parameter.TryGetValue("ErpUser", out var erpUserObj) ? erpUserObj as string : null;
            var locationKey = parameter.TryGetValue("LocationKey", out var locationKeyObj) ? locationKeyObj as string : null;
                       
            var result = new Dictionary<string, object>();
            result.Add("Message", new string[] {
                $"Standort: {locationKey}",
                $"Automatisch: {automatic}",
                $"Lokalisierung: {cultureId}",
                $"ERP-Benutzer: {erpUser}"
            });
            result.Add("MessageType", "Information");
            result.Add("PrintDocumentId", documentId);
            return result;
        }
    }
}

Auslöser

Bei jeder Aktion kannst du in der Karte „Ausführung bei“ Optionen wählen, die als Auslöser für die Aktion zur Verfügung stehen.
Folgende Werte können über den Eingabeparameter „TriggeredBy“ übergeben werden.
Nicht jede Aktion unterstützt jeden Auslöser. Welche Auslöser unterstützt werden, ist bei der jeweiligen Aktion vermerkt.

TriggeredBy IdentifiziererAusführung bei
addingPositionHinzufügen einer Position
addressChangeAdressänderung
afterCommitnach Übergabe an das ERP
beforeCommitvor Übergabe an das ERP
deliveryCountryChangeÄnderung des Lieferlandes
dynamicColumnInitializationautomatisch in dynamischer Spalte
manuallymanuelle Bestätigung über ein Kontextmenü, Drei Punkte-Menü oder einen Button
priceCalculationErmittlung von Preisen
transformationAfterConfirmWeiterverarbeitung, nach Bestätigung
transformationBeforeConfirmWeiterverarbeitung, vor Bestätigung
webhookAufruf eines Webhooks

Übersicht über die unterschiedlichen Aktionstypen

Adressprüfung

Diese Aktion ermöglicht es, bei jeder Änderung einer Adresse eine externe Adressvalidierung durchzuführen und dem Benutzer ggf. eine Korrektur vorzuschlagen. Das ist bei der Adresse im Kundenstamm sowie bei der Adresse oder der abweichenden Lieferadresse in Angeboten oder in Bestellungen möglich.

Folgende Angaben musst du – abweichend von den allgemeinen Angaben – vornehmen:

Wähle bitte den Aktionstyp „Adressprüfung“ aus.

Auslöser

In der Karte „Ausführung bei“ kannst du festlegen, wann die Adressprüfung ausgelöst wird. Hierbei steht dir nur die Option „Adressänderung“ zur Verfügung.

Wenn du „Adressänderung“ (TriggeredBy = „addressChange“) aktivierst, wird die Aktion immer ausgeführt, wenn der Benutzer

  • den Fokus auf einem der Adressfelder („Straße“, „PLZ“, „Ort“, „Land“) hatte und
  • der Inhalt eines der Adressfelder geändert wurde und
  • alle Adressfelder einen Inhalt haben und
  • der Fokus nicht mehr auf einem der Adressfelder ist.

Die Aktion wird zudem für Adressen in Deutschland nicht angestoßen, wenn die Leitcodierung für Deutschland in ELEMENTS aktiviert ist.

Die Aktion kann in diesen Entitäten ausgelöst werden:

  • Angebot (offer)
  • Bestellung (order)
  • Kunde (customer)

Eingabeparameter

Neben den allgemeinen werden zusätzlich diese Daten übergeben.

KeyDatentypValue
StreetAndHouseNumberstringStraße und Hausnummer
ZipCodestringPostleitzahl
CitystringStadt/Ort
CountryCodestringLändercode, z.B. DE

Es werden keine Positionsdaten übergeben.

Ausgabeparameter

Die Aktion erwartet entweder keine Rückmeldung (bei korrekter Adresse), eine Meldung mit Hinweis, Warnung oder Fehler (durch Fehler bei Adressvalidierung) oder die korrigierte Adresse.

Die Rückgabe von Dateien wird nicht unterstützt.

HINWEIS

Sobald die Prüfung innerhalb der Aktion eine korrigierte Adresse ermittelt, wird diese dem Benutzer in einer Lightbox mit der geprüften Adresse angezeigt. Der Benutzer kann dann entscheiden, ob er die korrigierte Adresse übernehmen oder ignorieren möchte.

Das sollten die übermittelten Werte sein:

KeyDatentypValue
StreetAndHouseNumberstringStraße und Hausnummer
ZipCodestringPostleitzahl
CitystringStadt/Ort
CountryCodestringLändercode, z.B. DE

Unvollständig zurückgegebene Adressen werden für die Anzeige um die Eingabeparameter ergänzt, so dass sichergestellt ist, dass vollständige Adressen verglichen werden.

Tritt ein Fehler auf, weil beispielsweise die API nicht erreichbar ist, dann sollten keine Adressdaten zurückgegeben werden. Message und MessageType werden dann analog zu den anderen Aktionen verarbeitet bzw. dargestellt.

HINWEIS

Artikel-Aktion

Diese Aktion kannst du in Abhängigkeit eines Artikels bzw. einer Position einsetzen. Sie lässt sich entweder über das Kontextmenü des Artikels/der Position aufrufen oder wird automatisch in den Details der Warenkorbposition oder in der Artikelübersicht eines Artikels angezeigt, der in der Artikelliste aktiviert ist.

Immer, wenn der Benutzer einen Artikel ansieht – sei es in der Artikelliste oder im Warenkorb – soll ein Preisvergleich eingeblendet werden. Dabei werden aktuelle Marktdaten über eine von der Aktion angefragten Schnittstelle im HTML-Format eingeblendet.

BEISPIEL

Immer, wenn der Benutzer einen Artikel ansieht – sei es in der Artikelliste oder im Warenkorb – sollen ihm alternative Artikel angezeigt werden, die er stattdessen anbieten kann. Dazu kannst du gemäß deiner eigenen Logik Artikel ermitteln, die du innerhalb der Aktion als Liste übergibst. Der Benutzer sieht dann die „alternativen“ Artikel und kann diese direkt in den Warenkorb übernehmen.

BEISPIEL

Wenn der Benutzer einen Artikel in einer Bestellung oder einem Angebot hinzufügt, möchte er wissen, ob und welchen preislichen Spielraum er noch hat. Diese Informationen stellst Du ihm anhand einer von dir hinterlegten Logik zur Verfügung. Er muss nur das Kontextmenü des Artikels auswählen und ihm werden die Informationen in einer Box im HTML-Format angezeigt.

BEISPIEL

Wähle bitte den Aktionstyp „Artikel-Aktion“ aus.

Auslöser

In der Karte „Ausführung bei“ kannst du festlegen, wann die Artikel-Aktion ausgelöst wird.

Wenn du „Manuelle Ausführung“ (TriggeredBy = „manually“) aktivierst, kann die Aktion vom Benutzer über das Kontextmenü angestoßen werden.

Aktivierst du „Automatisch in dynamischer Spalte“ (TriggeredBy = „dynamicColumnInitialization“) aktivierst, so wird die Aktion immer ausgeführt, wenn die Artikelübersicht in einer Artikelliste oder die Artikeldetails im Warenkorb angezeigt werden.

Beide Auslöser können in folgenden Entitäten angewendet werden:

  • Artikel (item)
  • Warenkorbposition (shoppingCartPosition)

In diesen Entitäten kann nur der Auslöser „Manuelle Ausführung“ angewendet werden, da die Infoleiste nicht zur Verfügung steht:

  • Angebotsposition (offerLine)
  • Bestellposition (orderLine)

Eingabeparameter

Neben den allgemeinen werden zusätzlich diese Paramater übergeben:

KeyDatentypValue
PriceListIdintdie ID der Preisliste, welche aktuell zugewiesen ist
DiscountListIdintdie ID der Rabattliste, welche aktuell zugewiesen ist
CurrencyCodestringdie Währung, welche aktuell zugewiesen ist
CurrencyCodeExchangeRatedecimalder aktuell verwendete Umrechnungsfaktor
HasGrossPricesbooldas Preiskennzeichen (brutto/netto)
AccountIdstringdie Kundennummer (KHKKontokorrent.Kto)
DocumentDatedatetimedas Belegdatum
PositionDictionary<string,object>[]Position / Artikel

Es werden die allgemeinen Positionsdaten übergeben.

Ausgabeparameter

Es werden die allgemeinen Rückmeldungen erwartet.

Zudem kannst du dem Benutzer bei der automatischen Ausführung in der dynamischen Spalte auch eine Liste an Artikeln anzeigen. Diese wird im Stil der anderen, mit dem Artikel in Beziehung stehenden Artikel angezeigt.

Und das sind die Inhalte, die du dafür mitgeben musst:

KeyDatentypValue
PositionGroupsDictionary<string,object>[]eine Liste von Positionsgruppen

Das sind die Ausgabeparameter in der PositionGroup:

KeyDatentypValue
ItemNumberstringdie Artikelnummer
VariationIdintdie interne Variantennummer (AuspraegungID)
Messagestringeine Meldung pro Position
SortOrderintSortierung der Position

Bei der Darstellung wird je nach Kontext unterschieden wie mit den Rückgabewerten umgegangen wird:

(a) Bei manueller Ausführung werden die zurück gegebenen Positionen verworfen und ausschließlich Messages angezeigt.

(b) Bei Einbettung in der dynamischen Spalte werden HTML Messages in einem iFrame dargestellt und nicht als Dialog.

HINWEIS

Bezahlung

Diese Aktion ermöglicht es, basierend auf der ausgewählten Zahlungsart in einem Angebot oder einer Bestellung eine externe Zahlungsabwicklung anzufragen und das Ergebnis der Anfrage zu verarbeiten. Während der Verarbeitung kann der Benutzer nicht in ELEMENTS arbeiten. Vielmehr muss er auf das Ergebnis der Aktion warten.

Der Benutzer wählt die ELEMENTS-Zahlungsart „Kreditkarte“ aus. Bei der Übergabe an das ERP-System wird in einem neuen Browser-Tab die Kreditkartenabwicklung aufgerufen. Diese muss der Benutzer durchlaufen. Sobald er dies erfolgreich gemacht hat, wird die Bestellung im ERP-System angelegt und die Transaktionsnummer wird in einem Feld in der Bestellung hinterlegt.

BEISPIEL

Wähle bitte den Aktionstyp „Bezahlung“ aus.

Auslöser

In der Karte „Ausführung bei“ kannst du festlegen, wann die Aktion ausgelöst wird.

Wenn du „vor Übergabe an das ERP“ aktivierst, wird die Aktion immer ausgeführt, wenn der Benutzer eine in der Aktion hinterlegte Entität an das ERP-System übergeben möchte (TriggeredBy = „beforeCommit“). Dann wird auch das Kennzeichen für die automatische Ausführung übergeben.

Die Aktion kann in diesen Entitäten ausgelöst werden:

  • Angebot (offer): Die Aktion wird ausgelöst, wenn der Benutzer auf „Angebot verbindlich bestätigen“ klickt.
  • Bestellung (order): Die Aktion wird ausgelöst, wenn der Benutzer auf „Bestellung verbindlich bestätigen“ klickt.

Die Aktion wird nur ausgeführt, wenn eine Bestellung oder ein Angebot neu in ELEMENTS angelegt wird. Zudem wird sie ausschließlich für konfigurierte ELEMENTS-Zahlarten (s. Administration / Zuordnungen / Bezahlung) ausgeführt.

HINWEIS

Die Aktion wird in zwei Schritten durchlaufen. Dabei werden jeweils Daten übergeben und Rückmeldungen verarbeitet.

Zahlungsprozess – Initialisierung

In einem ersten Schritt wird der Bezahlvorgang eingeleitet.

Eingabeparameter

Neben den allgemeinen werden zusätzlich diese Daten übergeben:

KeyDatentypValue
WebhookUrlstringfür diesen Prozess frisch generierte Rücksprung-URL für Zahlungsanbieter
ExternalEntityReferencestringdie ELEMENTS Referenznummer des Belegs
PaymentProcessStatusstringder Status des Prozesses (new | inProcess | finished | canceled | failed)
CurrencyCodestringdie Währung
GrossAmountdecimalder Gesamtbetrag der Entität

Es werden keine Positionsdaten übergeben.

Ausgabeparameter

Neben einem Sperrkennzeichen zum Abbruch des Prozesses, wird ein Token für den Folgeaufruf sowie eine URL zum Aufruf der Seite des Zahlungsanbieters für die Abwicklung der Bezahlung erwartet.

KeyDatentypValue
PreventsCommitbooldas Kennzeichen, ob die Übergabe an das ERP abgebrochen werden soll
PaymentProcessTokenstringder Token für Folgeaufruf (falls vorhanden)
PaymentProcessProviderUrlstringdie URL zum Aufruf der Seite des Zahlungsanbieters für die Abwicklung der Bezahlung

Zahlungsprozess – Abschluss

Im zweiten Schritt wird der Bezahlvorgang abgeschlossen. Der Schritt wird durch einen Webhook-Aufruf ausgelöst.

Eingabeparameter

Neben den allgemeinen werden zusätzlich diese Daten übergeben:

KeyDatentypValue
PaymentProcessTokenstringder Token aus Initialaufruf (falls vorhanden)
PaymentProcessStatusstringder Status des Prozesses (new | inProcess | finished | canceled | failed)
PaymentProcessWebhookResult_HttpHeaderDictionary<string,string>HttpHeader des Webhook-Aufrufs
PaymentProcessWebhookResult_HttpQueryDictionary<string,string>HttpQuery-Parameter des Webhook-Aufrufs
HttpBodystringder serialisierte Body des Webhook-Aufrufs

Ausgabeparameter

Es werden die allgemeinen Rückmeldungen erwartet.

Die Rückgabe von Dateien wird nicht unterstützt.

HINWEIS
KeyDatentypValue
PreventsCommitbooldas Kennzeichen, ob die Übergabe an das ERP abgebrochen werden soll
ExternalPaymentReferencestringdie Externe Zahlungsreferenz / TransactionID des Zahlungsanbieters (falls vorhanden)

Der Benutzer hat die Zahlungsart „Rechnung“ ausgewählt. Es muss keine externe Abwicklung durchlaufen werden.

BEISPIEL

Neben den allgemeinen Rückmeldungen kannst du die externe Zahlungsreferenz übergeben. Diese kann dann weiterverarbeitet werden, damit zum Beispiel die Buchhaltung neben der ELEMENTS Referenznummer die Referenznummer des Zahlungsanbieters einsehen kann.

Alternativ kannst du auch ein Sperrkennzeichen mitgeben. Sobald die Aktion feststellt, dass die Bestellung oder das Angebot nicht weiterverarbeitet werden kann, kann ein Sperrkennzeichen mitgeschickt werden. Dann ist es dem Benutzer nicht mehr möglich, die Bestellung oder das Angebot im ERP-System zu speichern.

Der Benutzer hat die Zahlungsart „Kreditkarte“ ausgewählt und die Abwicklung durchlaufen. Dabei ist es zu einem Problem gekommen. Die Bestellung kann somit auch nicht an das ERP-System übergeben werden. Es wird eine Fehlermeldung eingeblendet.

BEISPIEL

Schicke bei einer Sperrung bitte auch immer eine Fehlermeldung mit, damit der Benutzer auch reagieren und die Bestellung oder das Angebot anpassen kann.

TIPP

Einfache Belegaktion

Mit dieser Aktion bist du in der Lage Ihre Angebote, Bestellungen oder andere darin enthaltene Belege in andere Belege zu transformieren oder basierend auf einem Angebot oder einer Bestellung dem Benutzer weiterführende Informationen anzuzeigen.

Du möchtest, dass unter bestimmten Bedingungen eine Sofortrechnung – also die Kombination aus Lieferschein und Rechnung – aus ELEMENTS heraus erstellt werden kann, da ihr ein Ladengeschäft habt. Der Benutzer wählt im Kontextmenü der Bestellung einfach den Eintrag „Mitnahmedokumente erstellen” und es wird eine Sofortrechnung erzeugt und in ELEMENTS als Druckvorschau angezeigt.

BEISPIEL

Wähle bitte den Aktionstyp „Einfache Belegaktion“ aus.

Auslöser

In der Karte „Ausführung bei“ kannst du festlegen, wann die Aktion ausgelöst wird.

Wenn du „nach Übergabe an das ERP“ (TriggeredBy = „afterCommit“) aktivierst, wird die Aktion immer ausgeführt, wenn der Benutzer eine in der Aktion hinterlegte Entität an das ERP-System übergeben möchte. Dann wird auch das Kennzeichen für die automatische Ausführung übergeben.

Bei gewissen Konstellationen soll geprüft werden, ob ein Lieferdokument erzeugt werden kann. Das ist aber von verschiedenen Faktoren abhängig und diese Faktoren wiederum wirken sich darauf aus, ob und welcher Beleg erzeugt werden muss. Der Benutzer soll diese Prüfung aber nicht jedes Mal manuell über das Kontext- oder Drei Punkte-Menü anstoßen, sondern von dieser Prüfung nur das Ergebnis erhalten. Die Aktion wird also jedes Mal, wenn eine Bestellung an das ERP-System übergeben wird, durchlaufen. Der Benutzer bekommt davon entweder gar nichts mit, da kein Faktor für die Erstellung eines Lieferdokuments spricht. Alternativ wird dem Benutzer eine Fehlermeldung angezeigt, wenn zur Erstellung des Lieferdokuments mindestens ein Faktor nicht erfüllt ist. Im Idealfall wird dem Benutzer in der Druckvorschau das erstellte Lieferdokument angezeigt.

BEISPIEL

Wenn du möchtest, dass der Benutzer diese Aktion manuell mittels des Kontext- oder Drei Punkte-Menüs in der Entität ausführen kann, aktiviere die „Manuelle Ausführung“ (TriggeredBy = „manually“).

Die Aktion kann in diesen Entitäten ausgelöst werden:

  • Angebot (offer): Die Aktion wird ausgelöst, wenn der Benutzer auf „Angebot verbindlich bestätigen“ klickt.
  • Bestellung (order): Die Aktion wird ausgelöst, wenn der Benutzer auf „Bestellung verbindlich bestätigen“ klickt.

Eingabeparameter

Zusätzlich zu den allgemeinen Daten wird die interne Belegnummer übergeben.

KeyDatentypValue
DocumentIdintdie interne ID des Belegs

Es werden keine Positionsdaten übergeben.

Ausgabeparameter

Es werden die allgemeinen Rückmeldungen erwartet.

KeyDatentypValue
PrintDocumentIdintdie ID des Beleges, der in ELEMENTS ausgedruckt werden soll; es öffnet sich die in ELEMENTS bekannte PDF-Vorschau

Du lässt bei jeder Übergabe einer Bestellung an das ERP-System prüfen, ob eine Sofortrechnung erstellt werden soll. Das ist bei einer Versandart, die eine Lieferung mit sich bringt, aber gar nicht notwendig. Dann wird die Funktion durchlaufen, gibt aber kein Ergebnis an ELEMENTS zurück.

BEISPIEL

Du lässt bei jeder Übergabe einer Bestellung an das ERP-System prüfen, ob eine Sofortrechnung erstellt werden soll. Die Ware soll zwar mitgenommen werden, allerdings soll diese bar bezahlt werden und es gibt aber noch keinen Zahlungseingang auf die Bestellung. Dann wird der Benutzer darüber informiert, dass noch kein Zahlungseingang vorhanden ist und daher die Sofortrechnung nicht erstellt werden kann.

BEISPIEL

Du lässt bei jeder Übergabe einer Bestellung an das ERP-System prüfen, ob eine Sofortrechnung erstellt werden soll. Die Ware soll mitgenommen und bar bezahlt werden. Bei der Prüfung ist ein Zahlungseingang auf die Bestellung festgestellt worden und die Ware ist am Standort verfügbar. Daher wurde die Sofortrechnung erstellt und die Druckvorschau wird dem Benutzer angezeigt.

BEISPIEL

Inkassoart-Prüfung

Diese Aktion ermöglicht es, basierend auf der ausgewählten Zahlungsart in einem Angebot oder einer Bestellung eine Prüfung zu initiieren und dem Benutzer eine Information anzuzeigen. Mit Hilfe des Ergebnisses der Aktion kann die Übergabe eines Angebots oder einer Bestellung an das ERP-System unterbunden werden.

Der Benutzer wählt die ELEMENTS-Zahlungsart „Rechnung“ aus. Diese ist wiederum mit der Inkassoart „Kunde“ verknüpft und im Hintergrund wird eine Bonitätsprüfung ausgeführt. Diese meldet, dass anhand der vorliegenden Kriterien die Zahlung auf Rechnung nicht möglich ist. Der Benutzer bekommt einen Hinweis angezeigt und muss eine andere Zahlungsart auswählen.

BEISPIEL

Kunden, die seit zwei Jahren nicht mehr bestellt haben, dürfen nur bis zu einem Auftragswert von 100,- EUR auf Rechnung zahlen. Sobald der Auftragswert darüber liegt, wird dem Benutzer eine Warnung angezeigt und er kann die Bestellung nicht mehr an das ERP-System übergeben.

BEISPIEL

Jeder Zahlungsart in ELEMENTS ist eine Zahlungskondition im ERP-System zugewiesen. Idealerweise ist diese wiederum einer Inkassoart zugewiesen. Wenn nun der Benutzer eine Zahlungsart auswählt, sollte somit eine Inkassoart mit der Zahlungsart verknüpft sein. Diese Inkassoart kann die Aktion auslösen.

TIPP

Wähle bitte den Aktionstyp „Inkassoart-Prüfung“ aus.

Auslöser

In der Karte „Ausführung bei“ kannst du festlegen, wann die Aktion ausgelöst wird.

Wenn du „vor Übergabe an das ERP“ aktivierst, wird die Aktion immer ausgeführt, wenn der Benutzer eine in der Aktion hinterlegte Entität an das ERP-System übergeben möchte (TriggeredBy = „beforeCommit“). Dann wird auch das Kennzeichen für die automatische Ausführung übergeben.

Die Aktion kann in diesen Entitäten ausgelöst werden:

  • Angebot (offer): Die Aktion wird ausgelöst, wenn der Benutzer auf „Angebot verbindlich bestätigen“ klickt.
  • Bestellung (order): Die Aktion wird ausgelöst, wenn der Benutzer auf „Bestellung verbindlich bestätigen“ klickt.

Die Aktion wird nur ausgeführt, wenn eine Bestellung oder ein Angebot neu in ELEMENTS angelegt wird. Zudem wird sie nur ausgeführt, wenn die angegebenen Inkassoarten über eine ERP-Zahlungskondition mit einer ELEMENTS-Zahlungsart (s. Administration / Zuordnungen / Bezahlung) verknüpft sind.

HINWEIS

Eingabeparameter

Neben den allgemeinen werden zusätzlich diese Daten übergeben.

Es wird immer die Rechnungsadresse übergeben. Bei einem abweichenden Rechnungsempfänger wird dessen Rechnungsadresse übergeben.

HINWEIS
KeyDatentypValue
Name1stringder Name 1
Name2stringder Name 2
Additionstringder Zusatz
StreetAndHouseNumberstringdie Straße und Hausnummer
ZipCodestringdie Postleitzahl
Citystringdie Stadt / der Ort
CountryCodestringder Ländercode, z.B. DE
NetAmountdecimalder Nettobetrag
GrossAmountdecimalder Bruttobetrag
CurrencyCodestringdie Währung

Es werden keine Positionsdaten übergeben.

Ausgabeparameter

Es werden die allgemeinen Rückmeldungen erwartet.

Die Rückgabe von Dateien wird nicht unterstützt.

HINWEIS
KeyDatentypValue
PreventsCommitbooldas Kennzeichen, ob die Übergabe an das ERP abgebrochen werden soll

Der Benutzer hat die Zahlungsart „Rechnung“ ausgewählt und der Kunde hat die benötigte Bonität. Es wird keine Rückmeldung angezeigt.

BEISPIEL

Neben den allgemeinen Rückmeldungen kannst du auch ein Sperrkennzeichen mitgeben. Sobald die Aktion feststellt, dass die Bestellung oder das Angebot nicht weiterverarbeitet werden kann, kann ein Sperrkennzeichen mitgeschickt werden. Dann ist es dem Benutzer nicht mehr möglich, die Bestellung oder das Angebot im ERP-System zu speichern.

Der Benutzer hat die Zahlungsart „Rechnung“ ausgewählt und der Kunde hat nicht die benötigte Bonität. Die Bestellung kann somit auch nicht an das ERP-System übergeben werden. Es wird eine Fehlermeldung eingeblendet.

BEISPIEL

Schicke bei einer Sperrung bitte auch immer eine Fehlermeldung mit, damit der Benutzer auch reagieren und die Bestellung oder das Angebot anpassen kann.

TIPP

Position-Hinzufügen

Diese Aktion ermöglicht es, nach dem Hinzufügen einer Position oder dem Ändern des Lieferlandes im Angebot, in der Bestellung oder im Warenkorb Hinweise oder Fehlermeldungen in ELEMENTS anzeigen zu lassen. Damit kann sogar verhindert werden, dass ein Angebot oder eine Bestellung an das ERP-System übergeben wird.

Bestimmte Artikel können aufgrund behördlicher Regelungen nicht in ein Land geliefert werden. Sobald der Benutzer das Land als Lieferland angibt und einer der betreffenden Artikel in der Bestellung enthalten ist, wird der Benutzer darüber informiert und kann die Bestellung nicht mehr an das ERP-System übergeben.

BEISPIEL

Wähle bitte den Aktionstyp „Position-Hinzufügen“ aus.

Auslöser

Wenn du in der Karte „Ausführung bei“ die Option „Hinzufügen einer Position(TriggeredBy = „addingPosition“) aktivierst, wird immer beim Hinzufügen einer neuen Position die Aktion angestoßen.

Aktivierst du „Änderung des Lieferlandes(TriggeredBy = „deliveryCountryChange“), so wird immer bei der Änderung des Lieferlandes die Aktion angestoßen. Das kann passieren, wenn das Land in der Anschrift oder der abweichenden Lieferadresse geändert oder ein neuer Kunde hinzugefügt wird und sich dadurch das Land ändert.

Wenn du „vor Übergabe an das ERP(TriggeredBy = „beforeCommit“) aktivierst, wird die Aktion immer ausgeführt, wenn der Benutzer eine in der Aktion hinterlegte Entität an das ERP-System übergeben möchte. In diesem Fall ist das „Bestellung verbindlich bestätigen“ oder „Angebot verbindlich bestätigen“. Dann wird auch das Kennzeichen für die automatische Ausführung übergeben.

Die Aktion kann in diesen Entitäten ausgelöst werden:

  • Angebot (offer)
  • Bestellung (order)
  • Warenkorb (shoppingCart)

Eingabeparameter

Neben den allgemeinen werden zusätzlich diese Daten übergeben:

KeyDatentypValue
EntityTypestringder Typ der Entität, z.B. order für Bestellung
DeliveryAddressCountryCodestringder Ländercode des Lieferlandes (z.B. DE)
AccountIdstringdie Kundennummer (KHKKontokorrent.Kto), falls diese bereits in der Entität gesetzt ist
PositionsDictionary<string,object>[]die Positionsdaten

Es werden die allgemeinen Positionsdaten übergeben.

Bitte beachte, dass hier nicht der ELEMENTS-Versandtyp berücksichtigt wird. Es kann also nicht zwischen einer Lieferung und einer Mitnahme oder Abholung unterschieden werden.

HINWEIS

Ausgabeparameter

Es werden die allgemeinen Rückmeldungen erwartet, allerdings für die entsprechend hinzugefügte Position:

KeyDatentypValue
PreventsCommitbooldas Kennzeichen, ob die Übergabe an das ERP abgebrochen werden soll
PositionsDictionary<string,object>[]die Positionsdaten

Das sind die Ausgabeparameter der Position:

KeyDatentypValue
EntityKeystringder ELEMENTS-Key für diesen Datensatz
Messagestringeine Meldung pro Position (nur wenn diese nicht verkaufsfähig ist)
IsSaleablebooldas Kennzeichen für die Verkaufsfähigkeit des Artikels

Der Benutzer fügt der Bestellung eine Position hinzu. Die Aktion wird durchlaufen und stellt keine Kriterien fest, die diese Änderung beanstanden.

BEISPIEL

Der Benutzer fügt einer Bestellung, die in die Schweiz geliefert werden soll, eine Position hinzu. Dieser Artikel soll allerdings nur unter bestimmten Bedingungen in die Schweiz geliefert werden. Also erhält der Benutzer einen Hinweis an der Position, dass er den Kunden auf eine Besonderheit hinweisen soll. Die Bestellung kann dennoch an das ERP-System übergeben werden.

BEISPIEL

Neben den allgemeinen Rückmeldungen kannst du auch ein Sperrkennzeichen mitgeben.Sobald die Aktion feststellt, dass die Bestellung oder das Angebot nicht weiterverarbeitet werden kann, kann ein Sperrkennzeichen mitgeschickt werden. Dann ist es dem Benutzer nicht mehr möglich, die Bestellung oder das Angebot im ERP-System zu speichern.

Der Benutzer fügt einer Bestellung, die in die Schweiz geliefert werden soll, eine Position hinzu. Dieser Artikel darf allerdings nicht in die Schweiz geliefert werden. Also erhält der Benutzer eine Fehlermeldung an der Position, die ihn darauf hinweist, dass dieser Artikel nicht in die Schweiz geliefert werden kann. Er kann die Bestellung somit auch nicht an das ERP-System übergeben.

BEISPIEL

Schicke bei einer Sperrung bitte auch immer eine Fehlermeldung mit, damit der Benutzer auch reagieren und die Bestellung oder das Angebot anpassen kann.

TIPP

Position-Neuberechnung

Diese Aktion ermöglicht es, bei der Berechnung einer Position im Angebot, in der Bestellung oder im Warenkorb individuelle Konditionen in die Preisermittlung einfließen zu lassen.

Du möchtest, dass alle Artikel derselben Artikelgruppe einen Rabatt von 5 % erhalten, sobald drei Artikel dieser Artikelgruppe in einer Bestellung enthalten sind. Sobald einer dieser Artikel wieder entfernt wird, wird der Rabatt ebenfalls entfernt.

BEISPIEL

Wähle bitte den Aktionstyp „Position-Neuberechnung“ aus.

Auslöser

In der Karte „Ausführung bei“ kannst du festlegen, wann die Aktion ausgelöst wird.

Wenn Du „Ermittlung von Preisen“ (TriggeredBy = „priceCalculation“) aktivierst, wird die Aktion immer ausgeführt, wenn eine Änderung innerhalb der Entität zur Neuberechnung von Preisen führt. Welche Änderungen diese Neuberechnung veranlassen können, kannst du in der Hilfe unter <Bestellungen/Angebote > Bestellung/Angebot bearbeiten> einsehen.

Die Aktion kann in diesen Entitäten ausgelöst werden:

  • Angebot (offer)
  • Bestellung (order)
  • Warenkorb (shoppingCart)

Eingabeparameter

Neben den allgemeinen werden zusätzlich diese Daten übergeben:

KeyDatentypValue
PriceListIdintdie ID der Preisliste, welche aktuell zugewiesen ist
DiscountListIdintdie ID der Rabattliste, welche aktuell zugewiesen ist
CurrencyCodestringdie Währung, welche aktuell zugewiesen ist
CurrencyCodeExchangeRatedecimalder aktuell verwendete Umrechnungsfaktor
HasGrossPricesbooldas Preiskennzeichen (brutto/netto)
AccountIdstringdie Kundennummer (KHKKontokorrent.Kto)
DocumentDatedatetimedas Belegdatum
PositionDictionary<string,object>[]Position / Artikel

Es werden die allgemeinen Positionsdaten übergeben.

Das Kennzeichen, ob der Einzelpreis manuell verändert worden ist, kann genutzt werden, um Positionen mit einem individuellen Preis/Rabatt von der Neuberechnung auszuschließen.

TIPP

Ausgabeparameter

Es werden die allgemeinen Rückmeldungen erwartet, allerdings pro Position:

KeyDatentypValue
PositionsDictionary<string,object>[]die Positionsdaten

Das sind die Ausgabeparameter der Position:

KeyDatentypValue
EntityKeystringder ELEMENTS-Key für diesen Datensatz
UnitPricedecimalder Einzelpreis
DiscountValuedecimalder Rabattsatz (in Prozent)
IsManualPricebooldas Kennzeichen, ob der Einzelpreis manuell verändert worden ist (EinzelpreisManuell)

Sobald die Aktion also eine Änderung an den Positionskonditionen feststellt, kannst du diese an ELEMENTS übermitteln.

Das Kennzeichen, ob der Einzelpreis manuell verändert worden ist, kann genutzt werden, um Positionen von einer späteren Neuberechnung aufgrund einer Änderung an der Entität auszuschließen.

TIPP

Der Benutzer ändert den Preis eines Artikels. Diese Änderung wird durch die Aktion überprüft und stellt keine Bedingung für eine Änderung der Preise dar.

BEISPIEL

Der Benutzer ändert einen Preis und dieser ist zu gering. Der Benutzer bekommt eine Fehlermeldung angezeigt und muss den Preis wieder korrigieren. Alternativ kann die Aktion auch den korrekten Preis übergeben.

BEISPIEL

Warenkorb-Aktion

Diese Aktion kannst du nutzen, um im Kontext des Warenkorbs Prüfungen durchzuführen oder auch dem Benutzer Informationen anzuzeigen. Dabei kannst du auch verhindern, dass ein Warenkorb übergeben wird.

Der Benutzer hat einen Warenkorb befüllt, aber der Wert des Warenkorbs überschreitet einen gewissen Betrag. Die Aktion wird beim Klick auf „Bestellung“ ausgeführt und stellt fest, dass der Warenkorb nicht übergeben werden kann. Dem Benutzer wird eine Meldung im HTML-Format eingeblendet, die ihn auf den Grund hinweist.

BEISPIEL

Der Benutzer möchte weitere Informationen zum Warenkorb hinterlegen. Dazu kann er im Menü des Warenkorbs die entsprechende Aktion aufrufen. Ihm wird ein Webformular angezeigt, in dem er die fehlenden Daten eintragen kann. Diese werden mit der internen Referenznummer von ELEMENTS verknüpft.

BEISPIEL

Wähle hier bitte den Aktionstyp „Warenkorb-Aktion“ aus.

Auslöser

In der Karte „Ausführung bei“ kannst du festlegen, wann die Aktion ausgelöst wird.

Wenn du „Manuelle Ausführung“ (TriggeredBy = „manually“) aktivierst, kann die Aktion über das Drei Punkte-Menü des Warenkorbs angestoßen werden.

Aktivierst du „Weiterverarbeitung, vor Bestätigung“ (TriggeredBy = „transformationBeforeConfirm“) so kannst du automatisch die Aktion ausführen, wenn der Benutzer im Warenkorb auf die Schaltfläche „Preisanfrage“ oder „Bestellung“ klickt. Die Aktion wird also ausgeführt, bevor der Benutzer die Zusammenfassung der Preisanfrage oder Bestellung sieht.

Aktivierst du „Weiterverarbeitung, nach Bestätigung“ (TriggeredBy = „transformationAfterConfirm“) so kannst du automatisch die Aktion ausführen, wenn der Benutzer die Übergabe des Warenkorbs als Preisanfrage oder Bestellung abschließt. Die Aktion wird ausgeführt nachdem der Benutzer die Zusammenfassung der Preisanfrage oder Bestellung gesehen und diese bestätigt hat.

Zudem kannst du das Ergebnis der Aktion im Detailbereich des Warenkorbes automatisch anzeigen, wenn du „automatisch in dynamischer Spalte“ (TriggeredBy = „dynamicColumnInitialization“) aktivierst.

Die Aktion kann in diesen Entitäten ausgelöst werden:

  • Bestellanfrage (orderRequest): Das ist ein Warenkorb, den ein Business-Login als Bestellung übergeben hat. Dieser ist als Bestellanfrage gekennzeichnet und nur im ELEMENTS Commerce Cockpit verfügbar.
  • Business-Login-Warenkorb (reseller): Das ist ein Warenkorb, den ein Business-Login aktuell bearbeitet.
  • Preisanfrage (priceInquiry): Das ist ein Warenkorb, den ein Business-Login als Preisanfrage übergeben hat. Dieser ist als Preisanfrage gekennzeichnet und nur im ELEMENTS Commerce Cockpit verfügbar.
  • Warenkorb (default): Das ist der Warenkorb, den ein Benutzer in ELEMENTS anlegen kann. Dieser ist nur im ELEMENTS Commerce Cockpit verfügbar.
  • Webshop Warenkorb (externalBasket): Das ist der Warenkorb im ELEMENTS Commerce Cockpit, der mit einem Warenkorb eines 4SELLERS Webshops (bei aktivierter Schnittstelle) verknüpft ist.

Eingabeparameter

Neben den allgemeinen Daten werden zusätzlich folgende Daten übergeben:

KeyDatentypValue
TargetTypestringdas Ziel der Entität
• Warenkorbtyp (s. Auslöser)
• Bestellung (order)
• Angebot (offer)
ShoppingCartTypestringder Warenkorbtyp
PriceListIdintdie ID der Preisliste, welche aktuell zugewiesen ist
DiscountListIdintdie ID der Rabattliste, welche aktuell zugewiesen ist
CurrencyCodestringdie Währung, welche aktuell zugewiesen ist
CurrencyCodeExchangeRatedecimalder aktuell verwendete Umrechnungsfaktor
HasGrossPricesbooldas Preiskennzeichen (brutto/netto)
AccountIdstringdie Kundennummer (KHKKontokorrent.Kto)
DocumentDatedatetimedas Belegdatum
PositionDictionary<string,object>[]Position / Artikel

Zudem werden die allgemeinen Positionsdaten übergeben.

Ausgabeparameter

Neben den allgemeinen Rückmeldungen kannst du auch ein Sperrkennzeichen mitgeben. Sobald die Aktion feststellt, dass der Warenkorb nicht weiterverarbeitet werden kann, kann ein Sperrkennzeichen mitgeschickt werden. Dann ist es dem Benutzer nicht mehr möglich, den Warenkorb zu übergeben.

KeyDatentypValue
PreventsTransformbooldas Kennzeichen, ob die Transformation des Warenkorbs in den TargetType abgebrochen werden soll

Schicke bei einer Sperrung bitte auch immer eine Fehlermeldung mit, damit der Benutzer auch reagieren und den Warenkorb anpassen kann.

TIPP

Bei der Darstellung wird – je nach Kontext – unterschieden, wie mit der Rückgabe umgegangen wird.

(a) Bei manueller Ausführung wird das PreventsTransform-Kennzeichen verworfen und ausschließlich Messages angezeigt.

(b) Bei der Weiterverarbeitung werden Messages wie gewohnt in einer Lightbox dargestellt, die Weiterverarbeitung allerdings abhängig vom PreventsTransform-Kennzeichen abgebrochen.

HINWEIS