Import – Anbindung von Vorsystemen mittels ETL

Beschreibung

REWOO Scope stellt eine Schnittstelle bereit, um Daten aus anderen Systemen unmittelbar in REWOO Scope einzuspielen und auf die dortige Struktur abzubilden. Hierfür eventuell notwendige neue Strukturen können sowohl durch Kopieren von Vorlagen wie auch durch Ableiten aus einem vorhandenen Typ angelegt werden. Die Änderungen aus den Vorsystemen werden über Changesets in CSV-Dateien übergeben. Für eine weitere Transformierung der Daten in eine REWOO-konforme Struktur können Groovy-Skripte hinterlegt werden.

In diesen Skripten können auch vorhandene Daten in REWOO Scope abgefragt werden.

Für jedes Vorsystem muss eine eindeutige ID definiert werden – z. B. myCRM. Zusammen mit einer für dieses System eindeutigen ID für jeden Datensatz – z. B. REWOO-Kunden – ergibt sich daraus eine installationsweit eindeutige externe ID für diesen Datensatz: myCRM REWOO-Kunden. Ist also ein Element dem Scope-ETL bekannt gemacht worden, muss man den folgenden Datensätzen darauf achten, dass sowohl System-ID wie auch externe ID identisch sind, damit das Element identifiziert werden kann. Auch bei der Verwendung der externen ID als Kontext-ID wird die System-ID herangezogen, um das Kontext-Element zu bestimmen.

Ist die externe ID noch nicht verwendet worden und somit REWOO Scope unbekannt, wird der Datensatz über den Namen und den Typ zugeordnet, sofern er vorhanden ist, oder aus Typ oder Vorlage abgeleitet, falls er neu ist. Über den Action Type kann gesteuert werden, wie REWOO Scope auf diese Situationen reagieren soll.

Ist die externe ID bekannt, wird der Name und der Typ ignoriert, das Element identifiziert und die zugehörigen Daten aktualisiert.

Vorsystemspezifische Konfiguration

Für jedes Vorsystem müssen jeweils folgende Parameter definiert werden.
Der Name des Systems:
etlconfig.example.system = Example
Es wird ein ETL-Benutzer mit diesem Namen angelegt, der als Autor aller aus einem ETL-Import resultierender Werte eingetragen wird.
Das Passwort des ETL-Benutzers
etlconfig.example.password = oElxW3$
Optional ein Groovy-Skript, um den Import zu ändern oder zu ergänzen
etlconfig.example.transformscript = ./transform_example.groovy
Das Skript muss im Ordner rewoo-admin/storage/rewoo/etl/conf abgelegt werden.
Das Verzeichnis, in dem die ETL-Dateien abgelegt werden
etlconfig.example.inputdir = ./spool
Dieses Verzeichnis ist relativ zu rewoo-admin/storage/rewoo/etl/spool
Die Dateiendungen der ETL-Dateien
etlconfig.example.inputfiles = txt,TXT
Hier können eine oder mehrere mit Komma getrennte Dateiendungen angegeben werden, die die Import-Dateien kennzeichnen. Groß-/Klein-Schreibung wird beachtet, d.h. csv und CSV sind zwei unterschiedliche Endungen.

Input-Format

Die Changesets haben das Format:
(int; int; int; long; String; String; String; String; String; String)
Die Felder der Changesets haben folgende Bedeutung:

allgemein

  1. id (int primary key not null): fortlaufender Primärschlüssel über alle Changesets.
  2. actionType (int not null): Aktion, die für dieses Changeset gilt
    • CREATE_MODIFY(1) Element wird angelegt, wenn es nicht vorhanden ist, sonst geändert
    • COPY_MODIFY(3) Element wird von einer Vorlage kopiert, wenn es nicht vorhanden ist, sonst geändert
    • MATCH(4) Element ist vorhanden, dient zur Zuordnung von der externen ID zu existierenden, realen Elementen; Vorlagen können nicht bekannt gemacht werden.
    • ADD_FILE(5) nur für Dateilisten: an eine bestehende Liste wird eine Datei angehängt. Wenn in dieser Liste eine Datei gleichen Namens vorhanden ist, wird diese ersetzt.
    • CHANGE_STATE(6) Element wechselt seinen Status.
    • CHANGE_LAYOUT(7) Element wechselt sein Formular-Layout.
    • CHANGE_ROLE_SET(8) Element wechselt sein Rollen-Set.
  3. rewooType (int not null): einer aus
    • OBJECT(1)
    • PROCESS(2)
    • ASPECT(3)
    • NODE(4)
    • VALUE(7)
    • CONNECTION(8)
  4. timeStamp (long not null): Zeitstempel der Änderung; der Zeitstempel muss immer größer gleich dem Zeitstempel des Kontextes sein (Format: the number of milliseconds since January 1, 1970, 00:00:00 UTC)
  5. systemID (String not null): eindeutiger Name des Vorsystems
  6. externalID (String not null): eindeutiger Identifier bzgl. des Vorsystems, wird vom ETL festgelegt und zur Identifizierung bei Änderungen oder Entfernen oder zur Festlegung des Kontextes verwendet

actionType = CREATE_MODIFY und rewooType = OBJECT, PROCESS, ASPECT, NODE

  1. externalContextID (String): die externe ID des Kontextes falls bekannt, sonst null
    • bei OBJECT und PROCESS ist der Kontext immer null
    • bei ASPECT ist der Kontext das Objekt oder der Prozess
    • bei NODE ist der Kontext der Elternknoten oder der Aspekt
  2. modelType (String not null): Name des Typs, der instanziiert wird
  3. name (String not null): Name des Elements
  4. layoutName (String): Name des Layouts

actionType = COPY_MODIFY und rewooType = OBJECT, PROCESS, ASPECT, NODE

  1. externalContextID (String): die externe ID des Kontextes falls bekannt, sonst null
    • bei OBJECT und PROCESS ist der Kontext immer null
    • bei ASPECT ist der Kontext das Objekt oder der Prozess
    • bei NODE ist der Kontext der Elternknoten oder der Aspekt
  2. templateName (String not null): Name der Vorlage, die kopiert wird
  3. name (String not null): Name des Elements
  4. copyStrategy (optional, String, default: CONNECTED): Strategie, welche verbundenen Elemente ebenfalls kopiert werden sollen; entspricht der Strategie der COPY-Funktion; mögliche Werte: SINGLE, CHILDREN, CONNECTED

actionType = MATCH und rewooType = OBJECT, PROCESS, ASPECT, NODE

  1. externalContextID (String): die externe ID des Kontextes falls bekannt, sonst null
    • bei OBJECT und PROCESS ist der Kontext immer null
    • bei ASPECT ist der Kontext das Objekt oder der Prozess
    • bei NODE ist der Kontext der Elternknoten oder der Aspekt
  2. name (String not null): Name des Elements
  3. null
  4. null

actionType = CHANGE_STATE und rewooType = OBJECT, PROCESS, ASPECT, NODE, CONNECTION

  1. externalContextID (String): die externe ID des Kontextes falls bekannt, sonst null
    • bei OBJECT und PROCESS ist der Kontext immer null
    • bei ASPECT ist der Kontext das Objekt oder der Prozess
    • bei NODE ist der Kontext der Elternknoten oder der Aspekt
  2. null
  3. null
  4. state (String): Name des Status, den das Element haben soll:
    • ACTIVE
    • ON_HOLD
    • CLOSED
    • ARCHIVED
    • REJECTED

actionType = CHANGE_LAYOUT und rewooType = OBJECT, PROCESS, ASPECT, NODE, CONNECTION

  1. externalContextID (String): die externe ID des Kontextes falls bekannt, sonst null
    • bei OBJECT und PROCESS ist der Kontext immer null
    • bei ASPECT ist der Kontext das Objekt oder der Prozess
    • bei NODE ist der Kontext der Elternknoten oder der Aspekt
  2. null
  3. null
  4. layout (String): Name des neuen Layouts

actionType = CHANGE_ROLE_SET und rewooType = ASPECT, NODE

  1. externalContextID (String): die externe ID des Kontextes falls bekannt, sonst null
    • bei ASPECT ist der Kontext das Objekt oder der Prozess
    • bei NODE ist der Kontext der Elternknoten oder der Aspekt
  2. null
  3. null
  4. role set (String): Name des neuen Rollen-Sets oder leer, falls das Rollen-Set entfernt werden soll

actionType = CREATE_MODIFY und rewooType = VALUE

  1. externalContextID (String): die externe ID des Kontextes (Objekts, Prozesses, Knoten oder Beziehung) falls bekannt, sonst null
  2. valueType (String not null): String, Number, Date, Image, ExternalLink (http://...), Email (...@mail.net), Choice (Auswahl, wird als String gespeichert, die Auswahlmöglichkeiten stehen im Layout), Boolean (Wahrheitswert, true oder false), Spreadsheet (Syntax analog wie Table Markdown von MediaWiki)
  3. name (String not null): Name des Felds auf dem Formular
  4. value (String not null): der eigentliche Wert

actionType = ADD_FILE und rewooType = VALUE

  1. externalContextID (String): die externe ID des Kontextes (Objekts, Prozesses, Knoten oder Beziehung) falls bekannt, sonst null
  2. valueType (String not null): FileLinks
  3. name (String not null): Name des Dateifelds auf dem Formular
  4. value (String not null): der absolute Pfad auf die Datei

actionType = CREATE_MODIFY und rewooType = CONNECTION

(andere ActionTypes sind bei Beziehungen nicht möglich)
  1. externalID Node A (String not null): die externe ID des Knotens, an dem die Beziehung beginnt
  2. correlationType (String not null): Name des Beziehungstyps
  3. rights (String not null): zwei Zeichen für die Rechte vom Startknoten zum Zielknoten und vice versa
    • O (Null) keine Rechte
    • R Leserechte
    • W Lese- und Schreibrechte
    • A Rechte für Modelländerungen
  4. externalID Node B (String not null): die externe ID des Knotens, an dem die Beziehung endet

Restriktionen

Änderungen von REWOO-Typen, Vorlagen und Nachrichten sind vorerst nicht möglich.

Beispiel

Anmerkung: In die CSV-Dateien können keine Kommentare eingefügt werden. Im Beispiel sind die Kommentare nachträglich eingefügt, um den Inhalt zu erklären.
1. Ein bereits existierendes Objekt wird für das ETL ausgewählt
"1";"4";"1";"0";"myCRM";"REWOO";"";"REWOO";"";""
2. Die Aspekte von REWOO werden für das ETL ausgewählt, um sie als Kontext verwenden zu können
"2";"4";"3";"0";"myCRM";"REWOO Kunden";"REWOO";"Kunden";"";""
"3";"4";"3";"0";"myCRM";"REWOO Mitarbeiter";"REWOO";"Mitarbeiter";"";""
3. In den Aspekt "Kunden" (Zeile 2) wird ein Knoten für einen Kunden eingefügt bzw. aktualisiert
"4";"1";"4";"0";"myCRM";"Kunde 983";"REWOO Kunden";"Kunden";"Kunde 983";""
"5";"1";"7";"0";"myCRM";"Kunde_KU_NR";"Kunde 983";"String";"AG-Nummer";"983"
"6";"1";"7";"0";"myCRM";"Kunde_KU_NAME";"Kunde 983";"String";"AG-Name";"VisionHolz AG"
"7";"1";"7";"0";"myCRM";"Kunde_KU_LAND";"Kunde 983";"String";"Land";"D"
"8";"1";"7";"0";"myCRM";"Kunde_KU_PLZ";"Kunde 983";"String";"PLZ";"76131"
"9";"1";"7";"0";"myCRM";"Kunde_KU_ORT";"Kunde 983";"String";"Ort";"Karlsruhe"
"10";"1";"7";"0";"myCRM";"Kunde_KU_STRASSE";"Kunde 983";"String";"Straße";"Haid-und-Neu-Str. 7"
"11";"1";"7";"0";"myCRM";"Kunde_KU_DATUM";"Kunde 983";"Date";"Aufnahmedatum";"17.12.2008"
"12";"1";"7";"0";"myCRM";"Kunde_KU_ANPRECHP";"Kunde 983";"String";"Name";"Herr Dres"
"13";"1";"7";"0";"myCRM";"Kunde_KU_TELEFON";"Kunde 983";"String";"Telefon";"07215686656"
"14";"1";"7";"0";"myCRM";"Kunde_KU_WÄHRUNG";"Kunde 983";"String";"Währung";"Euro"
4. Ein neues Objekt wird mit Hilfe einer Vorlage "Projekt" angelegt
"15";"3";"1";"0";"myCRM";"Projekt 125";"";"Projekt";"Projekt 125";""
"16";"1";"7";"0";"myCRM";"Projekt_PJ_NR";"Projekt 125";"String";"Projektnummer";"125"
"17";"1";"7";"0";"myCRM";"Projekt_PJ_NAME";"Projekt 125";"String";"Projektname";"Sitzgruppe Gutholz"
"18";"1";"7";"0";"myCRM";"Projekt_PJ_BEGINN";"Projekt 125";"Date";"Projekt Beginn";"01.02.2011"
"19";"1";"7";"0";"myCRM";"Projekt_PJ_ENDE";"Projekt 125";"Date";"Projekt Ende";"25.04.2011"
"20";"1";"7";"0";"myCRM";"Projekt_PJ_LEITEREXTERN";"Projekt 125";"String";"Externe Projektleitung";"Dres"
5. Die Aspekte dieses Projekts werden für das ETL selektiert, um sie als Kontext verwenden zu können
"21";"3";"3";"0";"myCRM";"Projektleitung 125";"Projekt 125";"Projektleitung";"Projektleitung";"Max Neumann"
"22";"3";"3";"0";"myCRM";"Projektkunden 125";"Projekt 125";"Kunden";"Kunden";""
6. Im Aspekt "Projektkunden" wird ein Knoten für einen Projektkunden eingeführt bzw. aktualisiert
"23";"1";"4";"0";"myCRM";"Auftraggeber 125 983";"Projektkunden 125";"";"VisionHolz AG";""
7. Eine Beziehung zwischen dem Projektkunden (Zeile 23) und dem Kunden unter REWOO (Zeile 4) wird angelegt
"24";"1";"8";"0";"myCRM";"Kundenprojekt 125 983";"Auftraggeber 125 983";"Kundenprojekt";"R";"Kunde 983"
8. Der Knoten des Projektleiters wird dem ETL bekannt gemacht (MATCH)
"25";"4";"4";"0";"myCRM";"Projektleiter 193";"REWOO Mitarbeiter";"Neumann, Max";"";""
9. Eine Beziehung zwischen dem Mitarbeiter unter REWOO (Zeile 25) und der Projektleitung (Zeile 21) wird angelegt
"26";"1";"8";"0";"myCRM";"Projektleitung 193 125";"Projektleiter 193";"Projektleitung";"W";"Projektleitung 125"
10. Ein neuer Prozess wird mit Hilfe der Vorlage "AuftragsvorlageMöbelbau" angelegt
"27";"3";"2";"0";"myCRM";"Auftrag 471";"";"AuftragsvorlageMöbelbau";"Auftrag 471";""
"28";"1";"7";"0";"myCRM";"Auftrag_AB_NR";"Auftrag 471";"String";"Auftragsnummer";"471"
"29";"1";"7";"0";"myCRM";"Auftrag_AB_VERSIONSNR";"Auftrag 471";"String";"Auftragsversion";"1"
"30";"1";"7";"0";"myCRM";"Auftrag_AB_DATUM";"Auftrag 471";"Date";"Auftragsdatum";"01.02.2011"
"31";"1";"7";"0";"myCRM";"Auftrag_AB_ERLEDIGT";"Auftrag 471";"Boolean";"erledigt";"true"
"32";"1";"7";"0";"myCRM";"Auftrag_AB_ERLEDIGTDAT";"Auftrag 471";"Date";"Erledigungsdatum";"20.02.2011"
"33";"1";"7";"0";"myCRM";"Auftrag_AB_PJ_NR";"Auftrag 471";"String";"Projektnummer";"125"
"34";"1";"7";"0";"myCRM";"Auftrag_AB_BETRAG";"Auftrag 471";"Number";"Auftragswert";"8937.50EUR"
11. Die Aspekte des Auftrags werden dem ETL bekannt gemacht, um diese als Kontext verwenden zu können
"35";"3";"3";"0";"myCRM";"Controlling 471";"Auftrag 471";"Controlling";"Controlling";""
"36";"3";"3";"0";"myCRM";"Auftraggeber 471";"Auftrag 471";"Auftraggeber";"Auftraggeber";""
12. Eine Beziehung zwischen der Projektleitung (Zeile 21) und dem Controlling (Zeile 28) wird angelegt
"37";"1";"8";"0";"myCRM";"Projektcontrolling 125 471";"Projektleitung 125";"P-Controlling";"W";"Controlling 471"
13. Eine Beziehung zwischen dem Projektkunden (Zeile 23) und dem Auftraggeber (Zeile 29) wird angelegt
"38";"1";"8";"0";"myCRM";"Kundenauftrag 983 471";"Auftraggeber 125 983";"Kundenauftrag";"W";"Auftraggeber 471"
14. Der Status des Knotens des Projektleiters wird geändert (CHANGE_STATE)
"39";"6";"4";"0";"myCRM";"Projektleiter 193";"REWOO Mitarbeiter";"";"";"ON_HOLD"
15. Das Rollen-Set des Knotens des Projektleiters wird geändert (CHANGE_ROLE_SET)
"40";"8";"4";"0";"myCRM";"Projektleiter 193";"REWOO Mitarbeiter";"";"";"Projekt-Rollen"

Bulk-Operations - Manuelle Massenoperationen

Mit den Bulk-Operations steht im Admin-Panel ein Werkzeug zur Verfügung, durch das manuelle Änderungen an einer großen Menge von Datensätzen möglich sind, ohne jeden Datensatz einzeln bearbeiten zu müssen.

Mögliche Operationen

Folgende Operationen stehen zur Verfügung:

  • Änderung des Wertes eines spezifischen Feldes (set value)
  • Änderung des Status (change state)
  • Änderung des Layouts (change layout)
  • Änderung des Rollensets (change role set)
  • Kopieren einer Vorlage (copy sketch)
Änderung des Wertes eines spezifischen Feldes (set value)

Auf allen Datenblättern wird das angegebenen Feld mit dem angegebenen Wert versehen.

  • valueType - Der Feldtyp des zu verändernden Feldes. Nicht alle Feldtypen werden unterstützt. Dieses Feld muss auf allen Datensätzen vorhanden sein, auf die diese Operation angewandt werden soll.
  • name - Der Name des Feldes, das bearbeitet werden soll. Der Name muss exakt sein.
  • value - Der neue Wert, der in dieses Feld geschrieben werden soll.
Änderung des Status (change state)

Der Status aller ausgewählten Datensätze wird geändert.

  • state - Der gewünschte Zielstatus. Bitte beachten Sie, dass es nicht zu logischen Inkonsistenzen kommt. So kann zum Beispiel kein aktives Element (ACTIVE) unter einer Vorlage (IMAGINARY) vorkommen.
Änderung des Layouts (change layout)

Ein bestimmtes, vorliegendes Layout wird für alle selektierten Datensätze gesetzt.

  • layout - Der Name des Layouts, welches die Elemente verwenden sollen. Der Name muss exakt sein. Das Layout muss für alle selektierten Elemente im Typ angelegt sein.
Änderung des Rollensets (change role set)

Ein bestimmtes, vorliegendes Rollenset wird für alle selektierten Datensätze gesetzt.

  • roleSet - Der Name des Rollensets, welches die Elemente verwenden sollen. Der Name muss exakt sein. Das Rollenset muss für alle selektierten Elemente im Typ angelegt sein.
Kopieren einer Vorlage (copy sketch)

Unter alle selektierte Elemente wird ein neues Element aus der angegebenen Vorlage erzeugt.

  • sketchName - Name der Vorlage in der Welt. Der Ort der Vorlage in der Welt ist irrelevant. Aus diesem Grund ist es notwendig, dass die Vorlage einen eindeutigen Namen hat.
  • elementName - Name, den die erzeugten Elemente haben soll.

Selektion der zu ändernden Datensätze

Um eine Operation durchführen zu können, muss zunächst eine Anfrage erstellt werden, die alle Elemente auswählt, auf die die Operation angewandt werden soll. Dabei können sowohl sehr simple als auch recht komplexe, geschachtelte Anfragen erstellt werden, um sehr gezielt Elemente selektieren zu können.

Folgende Selektoren stehen zur Verfügung:

  • Name - Selektiert alle Elemente mit einem bestimmten Namen
  • Status - Selektiert alle Elemente mit einem bestimmten Status
  • Type - Selektiert alle Elemente eines bestimmten Typs
  • NodeType - Selektiert alle Elemente einer bestimmten Ebene eines Typs
  • Value - Selektiert alle Elemente, auf denen ein bestimmtes Feld einen bestimmten Wert hat

Anfragen können geschachtelt werden, so dass man zum Beispiel alle Elemente selektieren kann, die vom Typ "Auftrag" sind, den Status "ACTIVE" haben und auf denen das Feld "Auftragswert" größer als 0 ist.

Einschränkungen für "Value"

Programmbedingt müssen für "Value" bestimmte Vorschriften eingehalten werden, damit die Elemente richtig gefunden werden können. Diese sind wie folgt:

  • Boolean - Der Zustand auf Englisch: true oder false.
  • Condition - Der Zustand auf Englisch: true oder false.
  • Date - Muss in der Syntax des defaultServerLocale eingegeben werden. Das entspricht für de_DE zum Beispiel dd.mm.yyyy, für en_US allerdings mm/dd/yyyy.
  • Indicator - Der Zustand auf Englisch: rising, constant oder falling.
  • Number - Die Zahl muss exakt so sein, wie sie in der Datenbank hinterlegt ist. Ohne Tausendertrenner und Einheit, mit Dezimalpunkt statt -komma und mit exakt derselben Dezimalstellenanzahl. Deshalb eignet sich diese Anfrage nur bedingt für Währungsbeträge.
  • TrafficLight - Die Farbe der Ampel auf Englisch: green, yellow oder red.
Selektion ausführen

Ein Klick auf "Suchen" führt die Anfrage aus und zeigt folgend alle gematchten Elemente an. Damit kann auf die schnelle gesehen werden, ob die Anfrage alle und auch nur die gewünschten Elemente selektiert, oder ob weitere Anpassungen notwendig sind.

Durchführen einer Änderung

1. Korrekte Anfrage erstellen

Im ersten Schritt muss eine Anfrage erstellt werden, die genau die Elemente selektiert, auf die die Operation angewandt werden muss. Mehr Informationen dazu unter "Selektion der zu ändernden Datensätze".

2. Aktion festlegen

Im zweiten Schritt muss die Aktion beschrieben werden, die durchgeführt werden soll. Mehr Informationen dazu unter "Mögliche Operationen".

  • Vorsystem-ID - ETL-User oder Anwender-Login, dem diese Änderung zugeschrieben werden soll. Sie erscheint in REWOO Scope anschließend als Autor des Datenblatts beziehungsweise des neuen Datenblattversion.
3. CSV generieren

Nachdem die Elemente selektiert und die Aktion definiert wurde, muss nun das eigentliche CSV generiert werden, welches die Operation in ETL-Syntax umwandelt.

Alternativ kann auch eine auf dem Computer gespeicherte CSV-Datei über den Button "CSV laden" hineingeladen werden.

4. CSV ausführen

Die Aktion wird per Klick auf "CSV ausführen" durchgeführt. Soll die Aktion für eine spätere Wiederverwendung oder Bearbeitung gespeichert werden, kann das über die Schaltfläche "CSV speichern" durchgeführt werden.