Static File Erweiterung

Einleitung

Die Static File Erweiterung liest einen oder mehrere Textdateien und extrahiert Objektnamen und weitere Felder mit Hilfe eines regulären Ausdrucks. Für jeden Namen wird ein neues leeres Objekt im Datenspeicher erstellt. Wenn sich eine Datei ändert, wird sie automatisch erneut gelesen und die Objekte werden aktualisiert.

Diese Erweiterung wurde entwickelt, um Objekte aus speziellen Quellen einfach in das Raptor-System einzufügen. Alles, was du brauchst, ist ein einfacher Textexport aus dem externen System. Dies kann einfacher Text, eine kommagetrennte Liste, XML oder beliebige Textdaten sein, die mit regulären Ausdrücken abgeglichen werden können.

Fakten

Name

Static File

Bezeichner

StaticFile

Version

2.0

Funktionen

Quelle

Abschnitte

primary (optional, konfigurierbar)

Informationsblöcke

StaticFile[n] (optional, [n]=Nummer des Konfigurationseintrags)

Features

  • Liest eine oder mehrere Textdateien.

  • Die Datei wird automatisch nach einer Änderung erneut gelesen und alle Objekte im System werden aktualisiert.

  • Die Dateien können eine Vielzahl von Codierungen haben.

  • Das Parsen erfolgt mit leistungsfähigen regulären Ausdrücken mit der vollständigen Perl-Syntax.

So funktioniert die automatische Aktualisierung

Die Erweiterung überprüft das letzte Änderungsdatum, um zu entscheiden, ob die Datei erneut gelesen werden soll. Diese Überprüfung erfolgt alle zehn Sekunden.

Du musst sicherstellen, dass die Datei als atomare Operation geschrieben wird, da es sonst zu Zugriffskonflikten kommen kann, bei denen nur die Hälfte der Datei gelesen wird, weil der Schreibvorgang noch nicht abgeschlossen war.

Eine Datei als atomare Operation zu schreiben bedeutet, dass du den Export zunächst in eine separate Datei schreibst und anschließend eine einzelne Umbenennungs- oder Verschiebeoperation verwendest, um die vorherige Datei zu ersetzen.

Konfiguration

Das Konfigurationsschema

Module

StaticFile

List

Sources

Complex list definition

Value

SourcePath

String

  • Must be an existing file.

Value

SourceEncoding

Optional

String

  • Maximum length: 64

Default Value:

UTF-8

Value

ObjectContext

String

  • Must not be empty.

  • Maximum length: 64

  • Must match this regular expression:                             [-_.a-z0-9]+                        

Value

ObjectType

String

  • Must not be empty.

  • Must be one of this: Computer, User

Value

ParseRegExp

String

  • Must be a valid regular expression.

Value

ParseCaptureGroupForName

Optional

Integer

  • Minimum value: 1

  • Maximum value: 9

Default Value:

1

List

ObjectValues

Complex list definition

Value

Name

String

  • Must not be empty.

  • Maximum length: 64

  • Must match this regular expression: [_a-z0-9]+                                    

Value

Label

String

  • Must not be empty.

  • Maximum length: 64

Value

Section

Optional

String

  • Must not be empty.

  • Maximum length: 64

  • Must match this regular expression: [a-z0-9]+                                    

Default Value:

primary

Value

OrderIndex

Optional

Integer

  • Minimum value: 0

  • Maximum value: 1000

Default Value:

0

Value

DefaultValue

String

  • Maximum length: 1024

Die Liste Sources

Die Liste Sources enthält eine Liste von verschiedenen Dateiquellen, die in das Raptor-System importiert werden. Jeder Eintrag konfiguriert eine einzelne Datei, die mit einem angegebenen regulären Ausdruck geparst wird. Für jeden gefundenen Eintrag wird ein neues Objekt erstellt.

Mit der Liste ObjectValues können einzelne Werte zu den erstellten Objekten hinzugefügt werden. Diese Werte können Text aus der Quelldatei enthalten.

Die folgenden Abschnitte enthalten Details zu allen Konfigurationswerten für jeden Eintrag.

Der Wert SourcePath

Dieser erforderliche Wert muss der absolute Pfad zur Textdatei sein, die die externen Daten enthält. Der Pfad und die Datei müssen beim Start der Erweiterung vorhanden sein.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            <Value name="SourcePath">C:\Test\Import.txt</Value>
            ...
        </ListEntry>
    </List>
    ...
</Module>

Der Wert SourceEncoding

Verwende diesen Wert, um die Codierung der Textdatei festzulegen. Alle gängigen Codecs werden unterstützt. Wenn du diesen Wert weglässt, wird die UTF-8-Codierung angenommen.

Zeilenumbrüche werden nicht konvertiert. Wenn du reguläre Ausdrücke verwendest, die sich mit Zeilenumbrüchen befassen, denke daran, dass du ein Wagenrücklaufzeichen berücksichtigen musst, wenn der Text Windows-Zeilenumbrüche hat.

Eine kleine Auswahl möglicher Codecs findest du in dieser Liste:

  • ISO 8859-1 bis ISO 8859-10

  • UTF-8

  • UTF-16

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <Value name="SourceEncoding">UTF-8</Value>
            ...
        </ListEntry>
    </List>
    ...
</Module>

Der Wert ObjectContext

Gib den Standard-Kontextnamen für die erstellten Objekte an. Der Kontextname darf nicht länger als 64 Zeichen sein. Es dürfen auch nur Buchstaben, Zahlen und die Zeichen Bindestrich, Unterstrich und Punkt verwendet werden.

Du kannst denselben Kontextnamen verwenden, der bereits von anderen Quellen verwendet wird, oder einen eigenen Kontext verwenden, um die externen Objekte von anderen zu unterscheiden.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <Value name="ObjectContext">example.com</Value>
            ...
        </ListEntry>
    </List>
    ...
</Module>

Der Wert ObjectType

Gib den Standard-Objekttyp an, der aus den geparsten Daten der Textdatei erstellt wird. Es werden nur zwei Objekttypen unterstützt:

  • Computer

  • User

Dieser Wert ist case-sensitiv, stelle sicher, dass du die Typnamen wie gezeigt schreibst.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <Value name="ObjectType">Computer</Value>
            ...
        </ListEntry>
    </List>
    ...
</Module>

Der Wert ParseRegExp

Dies ist der reguläre Ausdruck, der verwendet wird, um die Objektnamen aus der Textdatei zu extrahieren. Jedes Vorkommen dieses regulären Ausdrucks wird verwendet, um ein Objekt zu erstellen.

Der reguläre Ausdruck benötigt mindestens eine Erfassungsgruppe, die für den Objektnamen verwendet wird.

Anfangs- und Endmarkierungen entsprechen Zeilenumbrüchen in der Textdatei. Wenn die Textdatei Wagenrücklaufzeichen enthält, musst du sie manuell abgleichen, um sie zu ignorieren.

Der reguläre Ausdruck unterstützt den vollen Funktionsumfang der Perl-Regular-Expressions, wie in der PCRE-Dokumentation beschrieben.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <Value name="ParseRegExp">^([^;]+)</Value>
            ...
        </ListEntry>
    </List>
    ...
</Module>

Der Wert ParseCaptureGroupForName

Verwende diesen optionalen Wert, um die Erfassungsgruppe zu ändern, die zum Extrahieren des Objektnamens verwendet wird. Wenn du diesen Wert weglässt, wird die erste Erfassungsgruppe verwendet, um den Namen zu extrahieren.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <Value name="ParseCaptureGroupForName">1</Value>
            ...
        </ListEntry>
    </List>
    ...
</Module>

Die Liste ObjectValues

Du kannst diese Liste verwenden, um zusätzliche Abschnitte und Werte zu jedem Objekt hinzuzufügen, das aus der Datei erstellt wird. Du musst diese Liste konfigurieren, aber wenn du diese Liste leer lässt, werden dem Objekt keine zusätzlichen Werte hinzugefügt.

Alle in dieser Liste konfigurierten Werte werden als ein einzelner Informationsblock mit dem Namen StaticFile[N] hinzugefügt, wobei [N] die Nummer des Konfigurationseintrags ist. Der erste Eintrag in der Konfiguration erstellt einen Informationsblock namens StaticFile1, der zweite StaticFile2 und so weiter.

Jeder Eintrag in dieser Liste konfiguriert einen einzelnen Wert für jedes Objekt. Du musst für jeden Wert einen eindeutigen Namen, ein im Client angezeigtes Label und einen Standardwert festlegen. Der Typ des Wertes ist immer String, der nicht geändert werden kann.

Du kannst Platzhalter im Standardwert verwenden, um den Text zu ändern und den Inhalt von Caption-Gruppen aus dem regulären Ausdruck zum Parsen zu verwenden.

Der Wert Name

Dies ist der eindeutige Name des Wertes. Die maximale Länge beträgt 64 Zeichen und es dürfen nur Buchstaben, Zahlen und das Unterstrichzeichen verwendet werden.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <List name="ObjectValues">
                <ListEntry>
                    <Value name="Name">BeispielWert</Value>
                    ...
                </ListEntry>
            </List>
            ...
        </ListEntry>
    </List>
    ...
</Module>
Der Wert Label

Dies ist das Label für den Wert, das im Client angezeigt wird. Die maximale Länge beträgt 1024 Zeichen, aber das Label sollte so kurz wie möglich gehalten werden.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <List name="ObjectValues">
                <ListEntry>
                    <Value name="Label">Beispiel Wert</Value>
                    ...
                </ListEntry>
            </List>
            ...
        </ListEntry>
    </List>
    ...
</Module>
Der Wert Section

Dies ist ein optionaler Wert. Wenn du ihn weglässt, verwendet die Erweiterung „primary“ als Abschnitt für den Wert. Du kannst einen beliebigen Abschnittsbezeichner angeben, um den Wert im gewünschten Abschnitt zu platzieren, oder du kannst einen neuen Abschnittsbezeichner angeben, um einen neuen Abschnitt zu erstellen.

Jeder Abschnittsbezeichner sollte mit einem Kleinbuchstaben beginnen und jedes folgende Wort sollte mit einem Großbuchstaben beginnen. Zum Beispiel wird der Abschnittsbezeichner greenEnergy im Client als „Green Energy“ angezeigt.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <List name="ObjectValues">
                <ListEntry>
                    ...
                    <Value name="Section">greenEnergy</Value>
                    ...
                </ListEntry>
            </List>
            ...
        </ListEntry>
    </List>
    ...
</Module>
Der Wert OrderIndex

Dieser Wert ist optional. Wenn du ihn weglässt, wählt die Erweiterung automatisch einen Reihenfolgen-Index für deinen Wert in der Reihenfolge, in der du die Werte konfigurierst.

Der Reihenfolgen-Index ist ein Wert zwischen 1 und 1000, der die Reihenfolge des Wertes in einer bestimmten Sektion definiert. Du kannst diesen Wert verwenden, um das Feld manuell in einer bestimmten Sektion zu platzieren.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <List name="ObjectValues">
                <ListEntry>
                    ...
                    <Value name="OrderIndex">10</Value>
                    ...
                </ListEntry>
            </List>
            ...
        </ListEntry>
    </List>
    ...
</Module>
Der Wert DefaultValue

Für jeden Eintrag musst du einen Standardwert festlegen, der den Text für den Wert enthält. Dieser Text wird für jedes Objekt verwendet, aber du kannst Platzhalter in den Text einfügen, um Inhalte der Erfassungsgruppen aus dem regulären Ausdruck zu verwenden.

Das Format des Platzhalters ist {cap:X}, wobei X eine Zahl von 1 bis 9 ist und eine der Erfassungsgruppen des regulären Ausdrucks anspricht. Schau dir Kapitel Beispiele an, um zu sehen, wie du diesen Platzhalter verwendest.

<Module name="StaticFile">
    ...
    <List name="Sources">
        <ListEntry>
            ...
            <List name="ObjectValues">
                <ListEntry>
                    ...
                    <Value name="DefaultValue">Beispiel: {cap:1}</Value>
                    ...
                </ListEntry>
            </List>
            ...
        </ListEntry>
    </List>
    ...
</Module>

Beispiele

Einfaches Beispiel

Das erste Beispiel zeigt eine vollständige, aber minimale Konfiguration für die Static File Erweiterung. Es verwendet einen einfachen regulären Ausdruck, um eine einfache kommagetrennte Liste zu parsen.

Es wird auf die Textdatei angewendet, die in Beispieldaten gezeigt wird. Diese Datei enthält eine Liste von Objekten, die aus einem fiktiven Serververwaltungssystem exportiert wurden.

Mit dem regulären Ausdruck werden die folgenden Computerobjekte aus der Datei extrahiert:

  • eduit00001@example.com

  • eduit00002@example.com

  • eduit00005@example.com

  • …

  • eduit00050@example.com

Wenn die Datei aktualisiert wird, werden alle Objekte automatisch erneut gelesen und die Änderungen im Datenspeicher vorgenommen.

 1<?xml version="1.0" encoding="UTF-8" ?>
 2<Configuration
 3        version="1"
 4        xmlns="http://educateit.ch/software/BlueStone/Configuration/1">
 5
 6    <Module name="StaticFile">
 7        <List name="Sources">
 8            <ListEntry>
 9                <Value name="SourcePath">C:\Test\Import.txt</Value>
10                <Value name="SourceEncoding">UTF-8</Value>
11                <Value name="ObjectContext">example.com</Value>
12                <Value name="ObjectType">Computer</Value>
13                <Value name="ParseRegExp">^([^;]+)</Value>
14                <Value name="ParseCaptureGroupForName">1</Value>
15            </ListEntry>
16        </List>
17    </Module>
18</Configuration>

Beispiel mit benutzerdefinierten Werten

Das zweite Beispiel verwendet mehr Informationen aus der Textdatei, die in Beispieldaten gezeigt wird.

Zuerst siehst du den erweiterten regulären Ausdruck, der eine zweite Fanggruppe hinzufügt, um die Werte in der zweiten Spalte der Datei zu erfassen.

^([^;]+);([^;]+)

Die erfassten Werte werden in den Text eingefügt, der in dem Wert DefaultValue konfiguriert ist, und verwenden {cap:1} und {cap:2}.

 1<?xml version="1.0" encoding="UTF-8" ?>
 2<Configuration
 3        version="1"
 4        xmlns="http://educateit.ch/software/BlueStone/Configuration/1">
 5
 6    <Module name="StaticFile">
 7        <List name="Sources">
 8            <ListEntry>
 9                <Value name="SourcePath">C:\Test\Import.txt</Value>
10                <Value name="SourceEncoding">UTF-8</Value>
11                <Value name="ObjectContext">example.com</Value>
12                <Value name="ObjectType">Computer</Value>
13                <Value name="ParseRegExp">^([^;]+);([^;)+)</Value>
14                <Value name="ParseCaptureGroupForName">1</Value>
15                <List name="ObjectValues">
16                    <ListEntry>
17                        <Value name="Name">userName</Value>
18                        <Value name="Label">User Name</Value>
19                        <Value name="DefaultValue">{cap:1}</Value>
20                    </ListEntry>
21                    <ListEntry>
22                        <Value name="Name">deviceId</Value>
23                        <Value name="Label">Device ID</Value>
24                        <Value name="DefaultValue">device:{cap:2}</Value>
25                    </ListEntry>
26                </List>
27            </ListEntry>
28        </List>
29    </Module>
30
31</Configuration>

Beispiel mit mehreren Dateien

Das letzte Beispiel liest mehrere Dateien. Jede Datei wird individuell konfiguriert. Die erste erstellt Computerobjekte und die zweite erstellt Benutzerobjekte.

 1<?xml version="1.0" encoding="UTF-8" ?>
 2<Configuration
 3        version="1"
 4        xmlns="http://educateit.ch/software/BlueStone/Configuration/1">
 5
 6    <Module name="StaticFile">
 7        <List name="Sources">
 8            <ListEntry>
 9                <Value name="SourcePath">C:\Test\Import1.txt</Value>
10                <Value name="SourceEncoding">UTF-8</Value>
11                <Value name="ObjectContext">example.com</Value>
12                <Value name="ObjectType">Computer</Value>
13                <Value name="ParseRegExp">^([^;]+);([^;]+)</Value>
14                <Value name="ParseCaptureGroupForName">1</Value>
15                <List name="ObjectValues">
16                    <ListEntry>
17                        <Value name="Name">example1</Value>
18                        <Value name="Label">Example 1</Value>
19                        <Value name="DefaultValue">Value 1</Value>
20                    </ListEntry>
21                    <ListEntry>
22                        <Value name="Name">example2</Value>
23                        <Value name="Label">Example 2</Value>
24                        <Value name="DefaultValue">Value 2</Value>
25                    </ListEntry>
26                    <ListEntry>
27                        <Value name="Name">captured1</Value>
28                        <Value name="Label">Captured 1</Value>
29                        <Value name="DefaultValue">Captured: {cap:1}</Value>
30                    </ListEntry>
31                    <ListEntry>
32                        <Value name="Name">captured2</Value>
33                        <Value name="Label">Captured 2</Value>
34                        <Value name="DefaultValue">{cap:2}</Value>
35                    </ListEntry>
36                </List>
37            </ListEntry>
38            <ListEntry>
39                <Value name="SourcePath">C:\Test\TestFile2.txt</Value>
40                <Value name="SourceEncoding">UTF-8</Value>
41                <Value name="ObjectContext">example.com</Value>
42                <Value name="ObjectType">User</Value>
43                <Value name="ParseRegExp">^(\w+)</Value>
44                <Value name="ParseCaptureGroupForName">1</Value>
45                <List name="ObjectValues">
46                    <ListEntry>
47                        <Value name="Name">name</Value>
48                        <Value name="Label">Name</Value>
49                        <Value name="DefaultValue">{cap:1}</Value>
50                    </ListEntry>
51                    <ListEntry>
52                        <Value name="Name">origin</Value>
53                        <Value name="Label">Origin</Value>
54                        <Value name="DefaultValue">User created by StaticFile source.</Value>
55                    </ListEntry>
56                </List>
57            </ListEntry>
58        </List>
59    </Module>
60</Configuration>

Beispieldaten

Der folgende Block zeigt, wie eine Textdatei aussehen könnte, die Daten enthält, die von der Erweiterung verarbeitet werden.

eduit00001;000741004382;example;;;;;
eduit00002;000741010626;example;;;;;
eduit00005;00074100F2A1;example;;;;;
eduit00006;000741010903;example;;;;;
eduit00007;00074101077A;example;;;;;
eduit00008;00074100F514;example;;;;;
eduit00009;00074100ACA7;example;;;;;
eduit00010;00074100F666;example;;;;;
eduit00011;000741010830;example;;;;;
eduit00012;000741010272;example;;;;;
eduit00013;000741004894;example;;;;;
eduit00020;000741000E90;example;;;;;
eduit00021;000741010505;example;;;;;
eduit00022;00074100CCF9;example;;;;;
eduit00024;000741000EA0;example;;;;;
eduit00026;000741004B60;example;;;;;
eduit00027;000741004AA1;example;;;;;
eduit00028;000741004B70;example;;;;;
eduit00038;00074100CC14;example;;;;;
eduit00039;000741010367;example;;;;;
eduit00042;00074101064C;example;;;;;
eduit00045;000741010307;example;;;;;
eduit00046;000741010700;example;;;;;
eduit00047;00074100F231;example;;;;;
eduit00048;00074100F31E;example;;;;;
eduit00049;00074101065E;example;;;;;
eduit00050;00074100F21E;example;;;;;