Lizenzmodul

Funktionalität

Mithilfe des banibis-Lizenzmoduls können Änderungen Ihres Lizenzbetreibers (Arrow, MSP, usw.. ) automatisch in banibis eingespielt werden. 

Da diese Änderungen in verschiedensten Formaten exportiert werden können, bieten wir mit einem kleinen Aufwand verbunden, dementsprechende Implementationen an. Standardmäßig kommt das Lizenzmodul allerdings mit einer vorkonfigurierten Implementation, die CSV-Dateien im hier beschriebenen banibis-Standard Format, interpretieren kann.

Diese CSV-Dateien werden über eine API in banibis importiert und dann weiterverarbeitet.

Banibis-Standard CSV-Format

Spaltentitel

Das banibis-Standard Format kann folgende CSV-Spaltentitel interpretieren:

Dabei ist zu beachten, dass die Spaltentitel (1. Zeile) identisch zu den, in blau gelisteten, Werten sind.

·         personIdentifier – verpflichtend

o   Daten Typ: Text [Person-Kennung]

·         personName – optional, ist für etwaige Nachverknüpfungen von Vorteil

o   Daten Typ: Text

·         productIdentifier – optional; wenn mehrere Produkte verknüpft sind -> verpflichtend

o   Daten Typ: Text [Bezeichnung aus Artikelstammdaten]

o   ACHTUNG! Falls Werte in dieser Spalte nicht dem exakten Produkttitel in banibis entsprechen, müssen die im CSV angegebenen Werte in den Artikeleigenschaften als alternativer „Identifikator“ eingetragen werden -> siehe Beispiel

·         costPrice – optional

o   Daten Typ: Double / Kommazahl

·         price – optional

o   Daten Typ: Double / Kommazahl

·         amount – optional

o   Daten Typ: Integer / Ganzzahl

·         billingInterval – optional

o   Daten Typ: Textwerte [per Year, One-Time, per Month(=default)] 

Trennzeichen

Mögliche Trennzeichen das banibis-Standard Formats:

·         ; - Semicolon

·         | - Pipe

Neue Zeilen werden immer durch Zeilenumbruch gekennzeichnet.

 

Beispiel CSV

Spaltentitel:
personIdentifier;personName;productIdentifier;amount;costPrice;price

Values:
kundenIdentifier123;banibis GmbH – Dresdnerstraße;prodIdentifier123;51;8,13;15,43

CSV in banibis importieren

Um die CSV-Dateien in banibis zu importieren und zu verwalten, bieten wir eine API-Schnittstelle an.

URL: https://instanz.banibis.at/rest/public/v1

·         INSERT CSV:

o    URL: /import/insert

o    Method: POST

o    Body Parameter:

§   “file“ – InputStream, CSV-Datei

§   “type“ – Text, gibt ImportTyp an

§   “filename“ – Text

§   “execute“ – Boolean, true = das file wird nach dem Upload direkt verarbeitet; false = es wird erst nach dem Aufruf des API-Calls /execute verarbeitet.

§   “config“ – Text, das mapping der Lizenz-Konfiguration angeben. (glob. Einstellung->Projekte->Lizenzmodul->Lizenz Import Konfiguration)

o    Returns: json-text

§   {
    "action": "insert import",
    "status": "success",
    "responseObject": {
        "id": 39331
    },
    "exceptions": []
}

o    Die zurückgegeben ID($.responseObject.id) wird in den unteren Calls verwendet

·         Status von einem Import:

o    URL: /import/status/{id}

o    Method: GET

o    {id} -> vom /import/insert retounierte ID

·         Status von mehreren Imports:

o    URL: /import/status

o    Method: POST

o    Body json: {"ids":[39330,39328,39329,39331]}

·         Execute Import:

o    URL: /import/execute/{id}

o    Method: GET

o    {id} -> vom /import/insert retounierte ID

·         Execute multiple Imports:

o    URL: /import/execute/

o    Method: POST

o    Body json: {"ids":[39330,39328,39329,39331]}

·         Delete Import:

o    URL: /import/delete/{id}

o    Method: POST

o    Body json: {"force":"false"}

o    force = true, löscht immer, force= false löscht nur falls noch nicht mit Abarbeitung begonnen (empfohlen)

·         Delete multiple Imports:

o    URL: /import/delete

o    Method: POST

o    Body json:{"ids":[39330,39328,39329,39331], "force":"false"}

 

Auf Anfrage können wir Ihnen gerne eine Postman Collection zur Verfügung stellen!

 

Erklärung Hinzufüge- und Editiermodus

In den globalen Einstellungen gibt es zwei Modi. Einträge neu hinzufügen und vorhandene Einträge editieren. Der Modus, der  rechts angezeigt wird, ist gerade aktiv. Möchte man den Modus wechseln, einfach auf den jeweiligen Button klicken.

In folgendem Beispiel ist „Hinzufügen“ aktiv.

Um den Modus zu wechseln, mit der Maus auf „Editiermodus“ klicken.

Modus „Hinzufügen“

Um einen neuen Eintrag zu erstellen, müssen die gewünschten Felder ausgefüllt und der Button Hinzufügen geklickt werden.

Achtung: der neue Eintrag bzw. die neuen Einträge werden erst mit dem Klick auf das Speichersymbol (grüner Haken) rechts oben angelegt.

 

Es ist im Hinzufügemodus auch möglich einen vorhandenen Eintrag zu kopieren. Das ist sinnvoll, wenn beispielsweise nur ein Feld geändert werden soll.

Im konkreten Beispiel wurde die erste Zeile markiert, die Warengruppe gewählt und auf Hinzufügen geklickt. Die Felder, Lizenz Konfiguration und Lizenz Produkte wurden somit nicht verändert, sondern einfach kopiert.

Den neuen Eintrag wieder mit dem Speichersymbol (grüner Haken) speichern.

 

Modus „Editieren“

Es werden vorhandene Einträge bearbeitet

·         Editiermodus klicken damit dieser aktiv ist

·         gewünschte Änderung durchführen und rechts auf „Editieren“ klicken, um eine Änderung auszulösen

·         Die Änderung mit dem Speichersymbol (grüner Haken) rechts oben speichern. (Die Änderung ist farblich markiert)

Aktivierung des Lizenz-Moduls

Um das banibis-Lizenzmodul zu verwenden, müssen entsprechende Rechte zugeteilt werden.
Zugriffe auf das Lizenzmodul-Center einrichten:

Unter Editoren -> globale Einstellungen -> Benutzer -> Center muss das Lizenz-Center konfiguriert werden.

Unter Center-Reiter kann der Reiter des Lizenz-Center hinzugefügt werden

Unter Center Zugang werden Zugriffsrechte für die entsprechenden Benutzer oder Gruppen hinterlegt. Im Feld Center muss der Eintrag Lizenz Importe ausgewählt werden.

Konfiguration eines Imports

Damit das Lizenzmodul einwandfrei funktionieren kann, müssen noch manuelle Konfigurationen vorgenommen werden.

Unter Editoren -> globale Einstellungen -> Projekte -> Lizenzmodul -> Lizenz Import Konfiguration können für die unterschiedlichen Anbieter, die Konfigurationen angelegt werden.

In diesem Beispiel sind Konfigurationen für einige Anbieter dargestellt:

Mapping: Das Mapping dient zur eindeutigen Identifikation des Files für den Import im banibis ERP. Wenn sich der Name des Files ändert, muss auch das Mapping im ERP auf den gleichen Namen angepasst werden.

Titel: Der Titel kann beliebig benannt werden. Das dient nur zur Kennzeichnung, um welchen Anbieter es sich handelt.

 

Wie werden Produkte verknüpft, die vom jeweiligen Import geändert werden dürfen?

Dies geschieht unter Editoren -> globale Einstellungen -> Projekte -> Lizenzmodul -> Lizenz Produkt Zuweisung.

Hier können die Produkte entweder im Multi-Feld Lizenz-Produkte einzeln angegeben werden oder über das Feld Warengruppe alle Produkte dieser Warengruppe zugewiesen werden.

 Unter Lizenz-Produkte können alle im ERP angelegten Artikel gewählt werden. Ebenso können alle im ERP angelegten Warengruppen ausgewählt werden.

Die Konfiguration ist für jeden Anbieter durchzuführen.

Wie werden Projekte/Personen verknüpft, die vom jeweiligen Import geändert werden dürfen?

Da die im Export angegebenen Kunden Identifikatoren oft stark variieren können (Kürzel, Firmennamen, usw..) müssen diese auch entsprechen mit den Accounts im banibis-ERP verknüpft werden.

Dies geschieht unter Editoren -> globale Einstellungen -> Projekte -> Lizenzmodul -> Lizenz Zuweisung.

Die Konfiguration der Zuweisung muss pro Lizenz-Import-Konfiguration für die jeweiligen Kunden und Projekte angelegt werden.

Hier ein konkretes Beispiel für Kunde "banibis" (Person ID) mit einem Projekt, der Person-Kennung "banibis.at" für die Lizenz-Import-Konfiguration "Banibis Test" und einem Rabatt von 10%.

 

Beschreibung der einzelnen Felder

Die Felder „Person ID“ & „Projekt“ (1&2) sind semi-optional:

Hier kann z.B. auch nur das Projekt gewählt werden und die Person ID frei bleiben (diese Einstellung nimmt dann die Person aus dem Projekt).

Falls das Standardprojekt eines Kunden verwendet werden soll, kann auch nur die Person ID gewählt werden, ohne ein Projekt anzugeben.

Achtung: der Kunde muss ein Standardprojekt hinterlegt haben, da es ansonsten eine Zuweisung nicht möglich ist!
Das Standardprojekt ist in den Stammdaten des Kunden zu hinterlegen!

Das Feld „Person-Kennungen" (3) ist verpflichtend:

Hier wird die im Export-CSV angegebene Kundenidentifikation hinterlegt! Falls im Feld „Lizenz Konfiguration“ (4) mehrere Import-Typen angegeben werden, müssen hier alle Kunden Identifikatoren hinterlegt werden (über + - Button).

Die Person-Kennung wird importiert und in einem CMDB-Objekt im ERP hinterlegt. Aus diesem kann die Person-Kennung genommen werden, wenn man das CSV-File nicht bei der Hand hat.

Einfach das Objekt mit Doppelklick in der Liste Lizenz-Importe öffnen die Person-Kennung mit Strg+C & Strg+V kopieren und in der Lizenz-Zuweisung einfügen.

              

         

Das Feld „Lizenz-Konfiguration“ (4) ist verpflichtend:

Hier muss der entsprechende Lizenz-Import Typ angegeben werden.

Es ist auch möglich, dass ein Projekt von mehreren Lizenz-Import Typen bearbeitet werden kann. Dazu einfach den +-Button des Feldes drücken und die gewünschten Lizenz-Import Typen hinzufügen.

Das Feld „Rabatt“ (5) ist optional:

Dieses Feld dient dazu, um Kunden (beispielsweise Reseller-Kunden) einen Rabatt zuweisen zu können. Dieser wird dann automatisch in die Projektposition für die Abrechnung übernommen.

Achtung: der Rabatt ist zwischen 0 und 1 zu wählen, wobei 0 = 0 % und 1 = 100% sind.
z.B. 0,1 = 10 %

Im konkreten Beispiel sind Reseller-Kunden eine eigene Kategorie und somit auch farblich gekennzeichnet:

Abarbeitung der Änderungen

Das durch die API hochgeladene CSV wird vom Job License Persistor Job interpretiert und in die Liste Lizenz Importe gesetzt.

Der Job kann unter Widgets -> System-Monitor gestartet werden.

Dazu muss zuerst im Widget auf "hier klicken" geklickt werden, um die Jobs zu öffnen und mit einem Klick auf den Aktions-Button "manuell starten", wird der Job gestartet. 

Im konkreten Fall, hat der Job jedoch ein automatisch Intervall von 30 Sekunden eingestellt, damit dieser nicht manuell gestartet werden muss.

Um die Änderungen abarbeiten zu können, muss das Lizenz-Center im Menu unter Listen à Lizenz Importe geöffnet werden

Die Daten aus dem CSV sind in dieser Liste bereit zur Abarbeitung.

 

In dieser Liste gibt es 3 Buttons für die Abarbeitung:

1 1) Änderungen testen wird automatisch beim Import ausgeführt und befüllt die Spalte Aktion mit einer schriftlichen Beschreibung der Änderung.

2 2) Änderungen ausführen führt die beschriebenen Änderungen aus.

3 3) Neu zuweisen kann verwendet werden, falls die automatische Zuweisung von Produkten, Personen oder Projekten nicht automatisch funktioniert hat, diese müssen dann richtig konfiguriert werden.

Im Projekt werden die Positionen, mit den Werten aus dem Import, neu hinzufügt oder bestehende Positionen verändert.

 

Die Spalte Rate in der Liste „Lizenz-Importe“ ist ein Wahrscheinlichkeitswert für die Änderung. Beispielsweise ist eine Änderung von 10 Lizenzen auf 11 Lizenzen sehr wahrscheinlich. Hingegen eine Änderung von 10 Lizenzen auf 20 Lizenzen nicht sehr wahrscheinlich, hat daher eine geringere Rate und muss manuell geprüft werden.

Diese Rate wird auch verwendet für die Automatische Ausführung der Änderungen.
Dazu ist der Job License Action Execution Job vorkonfiguriert. 

License Action Execution Job und License Persistor Job

Die Jobs ist unter globale Einstellungen -> Cron Jobs -> Jobs zu finden.

Die execTolerance bestimmt welche Einträge aus der Liste automatisch abgearbeitet werden sollen und welche nicht. Die Einstellung 0.9 führt alle Änderungen mit einer Rate von 90% und höher aus, die restlichen müssen also manuell nachgeprüft und über die in der Liste vorhandenen Buttons ausgeführt werden.