Eigenständig    ::    Als Add-On (API)    ::    In ISEntial integriert

Programmaufruf

Die gesamte Programmsteuerung und Kommunikation zwischen Anwendung und ISEdoc wird über die leistungsfähige Text-Schnittstelle abgewickelt, welche alle Daten (Befehle und Nutzdaten) über eine Parameterdatei übermittelt. In einer der nächsten Versionen sind weiter Schnittstellen wie z. B. eine REST-Schnittstelle geplant.

Eine für später angedachte Erweiterung der Schnittstelle betrifft das Zusammenspiel von ISEntial und ISEdoc. Hier sollen die Daten direkt aus der Datenbank ermittelt werden. Dazu muss ISEntial bei der Archivierung eines neuen Dokumentes die UID des Datensatzes (Unique Identifier wie z. B. UUID oder Microsofts GUID) mit der benötigten Information (Datenbanktabelle DBARCHIVREF, Datenfeld DBARCHIV.UID) über die Parameterdatei oder die REST-Schnittstelle übergeben werden. Nicht vorhandene (also neue) Datensätze müssen von ISEntial vor dem Aufruf erstellt und gespeichert werden. ISEdoc ermittelt daraus die benötigte Information.  Falls notwendig, ändert bzw. ergänzt ISEdoc die betroffenen Datensätze.

Die im vorigen Abschnitt beschriebene Erweiterung kann auch im Auftrag für andere Systeme realisiert werden. Nehmen Sie diesbezüglich Kontakt mit uns auf. Wir beantworten gerne Ihre Fragen.

Parameterdatei

Dem Programm wird stets eine Parameterdatei übergeben, die dazu benutzt wird, Befehle, Daten und Einstellungen zu übermitteln. Hierbei handelt es sich um eine Textdatei. Der Stammname der Datei und deren Speicherort sind unerheblich. Allerdings sollte die rufende Anwendung dafür sorgen, dass der Dateiname immer eindeutig ist, damit eine bereits bestehende und noch in Verwendung stehende Parameterdatei durch mehrmalige Programmaufrufe nicht überschrieben wird. Das kann z. B. durch einen  Zeitstempel im Dateiname erreicht werden.

Der Dateiname sollte mit Anführungszeichen angegeben werden, um keine Probleme mit Whitespaces zu bekommen.

Angaben innerhalb der Parameterdatei wie z. B. Dateinamen sollten ohne Anführungszeichen angegeben werden. Je Zeile darf nur ein Befehl angegeben werden.

Es gibt grundsätzlich drei Arten von Befehlen:

• Ohne Parameter
  Ein Befehl ohne Parameter steht alleine am Zeilenanfang. Weitere Angaben in derselben Zeile sind nicht erlaubt.
  
  
• Mit einem Parameter
  Ein Befehl mit Parameter steht ebenfalls am Zeilenanfang. Unmittelbar danach wir dieser durch einen Doppelpunkt von seinem Parameter getrennt. Weiter Angaben in derselben Zeile sind nicht erlaubt.
  
  
• Mit zwei Parametern
  Hier wird der Befehl vom Rest ebenfalls durch einen Doppelpunkt getrennt. Der Wert rechts nach dem Doppelpunkt wird erneut interpretiert: Ein Gleichheitszeichen trennt Parameter und Wert. Diese Befehlsart wird vorwiegend zur Übermittlung von Datenbankwerten verwendet..

Wichtig

Falls Befehle verwendet werden, die Änderungen im Archiv hervorrufen (z. B. "store" oder "modify"), sollte die rufende Anwendung auf die Beendigung von ISEdoc warten. Das ist wichtig, denn ISEdoc liefert nach Beendigung alle Werte wieder zurück, damit die rufende  Anwendung diese weiter verarbeiten kann (z. B. in ihre Datenbank speichern).

Die aktuellen Werte aller Felder werden beim Programmende in die Parameterdatei zurückgeschrieben, damit die rufende Anwendung geänderte Werte verarbeiten kann.

Befehle und Parameter innerhalb der Parameterdatei

cmd – Mit cmd eingeleitete Hauptbefehle

Jeder Aufruf von ISEdoc stellt einen einzelnen Befehl dar. Aus diesem Grund darf in der Parameterdatei der mit "cmd" eingeleitete Befehl nur einmal vorkommen. Dieser sollte der Übersichtlichkeit halber ganz vorne stehen.

Der durch "cmd" eingeleitete Hauptbefehl ist durch einen Doppelpunkt getrennt. Folgende Hauptbefehle werden unterstützt:

create_archive

Erstellt ein neues Archiv an dem durch "archive_root" angegebenen Ort. Voraussetzung dafür ist, dass der in "archive_root" angegebene Ordner bereits existiert und leer ist. Ansonsten bricht der Befehl mit einem Fehler ab.

store

Neues Dokument archivieren.

Wenn der Befehl "gui" (siehe weiter unten) mit angegeben wird, wird die Benutzerschnittstelle (GUI) angezeigt. Hier kann der Anwender Änderungen vornehmen bzw. ein zu archivierendes Dokument manuell auswählen.

Wurde der Befehl "gui" nicht angegeben, speichert ISEdoc das in DBARCHIV.QUELLPFAD angegebene Dokument automatisch im Hintergrund.

Die für das Archivieren notwendigen Werte werden mit Hilfe von Feldern an ISEdoc übergeben. Weitere Infos darüber finden Sie weiter unten unter "db_field".

Zurzeit werden folgende Felder unterstützt:

DBARCHIV.UID
DBARCHIV.MUID
DBARCHIV.MTABLE
DBARCHIV.DATEINAME
DBARCHIV.CONTAINER
DBARCHIV.CONTAINERGRUPPE
DBARCHIV.FUNKTIONSTYP
DBARCHIV.KURZBESCHREIBUNG
DBARCHIV.STICHWORTE
DBARCHIV.QUELLPFAD

Eine Beschreibung dieser Felder finden Sie weiter unten in diesem Dokument.

Falls ISEdoc mit einem Fehler terminiert oder der Anwender den Archivierungsvorgang ohne speichern beendet, muss die rufende Anwendung eventuell vorher erstellte, aber nicht verwendete Datensätze löschen.

modify

Ändert die Eigenschaften (Metadaten wie z. B. Stichworte, Beschreibung usw.) bzw. den Inhalt eines archivierten Dokumentes.

Wenn der Befehl "gui" (siehe weiter unten) mit angegeben wird, wird die Benutzerschnittstelle (GUI) angezeigt. Hier kann der Anwender Änderungen der Metadaten vornehmen bzw. das zu archivierende Dokument ersetzen.

Wurde der Befehl "gui" nicht angegeben, speichert ISEdoc alle Angaben automatisch im Hintergrund.

Besonderheiten im Zusammenhang mit der Angabe des Befehls "gui"

1. Metadaten müssen in den dafür vorgesehenen Feldern übergeben werden. Fehlt diese Angabe, so werden diese mit Standardwerten initialisiert. Für die Felder DBARCHIV.KURZBESCHREIBUNG und DBARCHIV.STICHWORTE ist der Standardwert eine leere Zeichenkette.
2. Wird "DBARCHIV.QUELLPFAD" nicht angegeben bzw. der übergebende Wert ist leer, fügt ISEdoc automatisch den in den Metadaten verwalteten Wert hinzu und liefert diesen beim Programmende an die rufende Anwendung zurück.
3. Wird in DBARCHIV.QUELLPFAD ein Wert angegeben, vergleicht ISEdoc diesen mit dem in den Metadaten gespeicherten Wert für den Quellpfad:

• • • • • Sind die Werte gleich, zeigt ISEdoc das archivierte Dokument an.
        • Sind die Werte ungleich, sucht ISEdoc nach dem in DBARCHIV.QUELLPFAD angegebene Dokument und zeigt dieses an. ISEdoc zeigt einen Hinweis an, der den Anwender darauf aufmerksam machen soll, dass ein anderes als das archivierte Dokument angezeigt wird.
        • Falls das in DBARCHIV.QUELLPFAD angegebene Dokument nicht gefunden werden kann, wird eine Fehlermeldung ausgegeben und die Programmverarbeitung abgebrochen.

delete

Löscht das im Feld DBARCHIV.DATEINAME angegebene Dokument aus dem Archiv endgültig.

Hinweise für Fremdsysteme

Soll ein Dokument gelöscht werden, so darf dies erst dann geschehen, wenn kein Datensatz mehr auf das Dokument verweist. Ansonsten dürfen nur die entsprechenden Datensätze gelöscht werden, die auf das Dokument verweisen. Daher sollte man bei jedem Löschen die Anzahl Verweise überprüfen: Löscht man den letzten Verweis, so kann das Dokument endgültig gelöscht werden.

Das hat zur Folge, dass der Löschvorgang zunächst nur innerhalb von der rufenden Anwendung stattfindet. Erst nachdem der letzte Verweis entfernt wurde, sollte der Löschbefehl abgesetzt werden. ISEdoc löscht dann das Dokument sofort und ohne Rückfrage. Somit ist allein die rufende Anwendung für die Verwaltung zuständig, was eine Integration in andere Systeme erleichtert.

print

Druckt die im DBARCHIV-Datensatz archivierte Datei auf dem im Befehl print_to übergebenen Drucker aus.

extract

Extrahiert die im DBARCHIV-Datensatz archivierte Datei an den im Befehl extract_to übergebenen Speicherziel.

view

Zeigt die im DBARCHIV-Datensatz archivierte Datei im Vorschaubereich an. In dieser Betriebsart sind Änderungen nicht möglich. Allerdings kann das angezeigte Dokument gedruckt bzw. aus dem Archiv extrahiert werden.

exist

Prüft das Vorhandensein eines archivierten Dokumentes. Das Ergebnis wird in "return_value" zurück geliefert:

• "return_value:0" Dokument existiert nicht.
• "return_value:1" Dokument existiert.

db_ – Datenbankunterstützung bzw. Schnittstelle

Diese Befehle bzw. Parameter sind für die Datenbankschnittstelle zuständig.

db_field:Datenbanktabelle.Feld = Wert

Mit "db_field" übergibt die rufende Anwendung Feldwerte an ISEdoc. Die unterstützten Felder werden weiter unten im jeweiligen Abschnitt "text" oder "isential" beschrieben.

db_field_ret:Datenbanktabelle.Feld = Wert

Mit "db_field_ret" übergibt ISEdoc alle Feldwerte an die rufende Anwendung zurück. Die unterstützten Felder werden weiter unten im jeweiligen Abschnitt "text" oder "isential" beschrieben.

db_interface:text|isential

Gibt die zu verwendete Schnittstelle zwischen der rufenden Anwendung und ISEdoc an.

Mögliche Werte sind "text" oder "isential".

Standarwert: text

text

Verwendet die Textschnittstelle. Die rufende Anwendung übergibt alle Daten über die Parameterdatei. Diese sollte vor dem Aufruf von ISEdoc so eingestellt sein, dass ISEdoc Lese- und Schreibzugriff bekommt. Nachdem ISEdoc mit seiner Arbeit fertig ist, werden etwaige Änderungen über dieselbe Parameterdatei dem Host mitgeteilt. Feldwertänderungen werden mit dem Befehl "db_field_ret" zurückgegeben.

Folgende Werte (Datenbankfelder) werden über die Textschnittstelle an ISEdoc übergeben:

DBARCHIV.UID

UID (Unique Identifier wie z. B. UUID oder Microsofts GUID) des übergebenen Datensatzes.

Bezogen auf ISEntial entspricht dieses Feld DBARCHIVREF.UID. Hiermit ließe sich der Wert des Feldes DBARCHIVREF.CUID ermitteln, welcher auf DBARCHIV.UID zeigt.

DBARCHIV verwaltet in ISEntial alle archivierten Dokumente. Für jedes Dokument gibt es einen eindeutigen Eintrag in dieser Tabelle.

DBARCHIVREF ist eine Tabelle, welche die Referenzen zu den archivierten Dokumenten verwaltet. Wenn z. B. in drei unterschiedlichen Systembereichen auf das gleiche Dokument verwiesen wird, gibt es für jeden dieser Bereiche einen Eintrag in DBARCHIVREF. Jeder dieser drei Einträge enthält im Feld DBARCHIVREF.CUID denselben Wert. Dieser zeigt auf DBARCHIV.UIDund entspricht dem archivierten Dokument. Das Dokument selbst ist dabei nur einmal im Archiv gespeichert.

DBARCHIV.MUID

UID (Unique Identifier wie z. B. UUID oder Microsofts GUID) des übergebenen Datensatzes.

Bezogen auf ISEntial entspricht dieses Feld dem Datensatz, mit dem das Dokument verbunden ist. Zusammen mit dem Feld DBARCHIV.MTABLE kann der Datensatz in ISEntial eindeutig identifiziert werden.

Beispiel:

DBARCHIV.MUID = '2fbc85ece79b4c469766bb92312b40c6'
DBARCHIV.MTABLE = 'DBVERKAUFSKOPF'

Mit diesen Angaben identifiziert man eindeutig den Auftrag 10254 vom 31.12.2018

DBARCHIV.MTABLE

Dieses Feld gibt den Namen der Tabelle an, die den im DBARCHIV.MUID angegebenen Datensatz enthält (s. a. DBARCHIV.MUID).

DBARCHIV.DATEINAME

Gibt den Dateinamen im Archiv an. Dieser wird wie folgt gebildet:

Containergruppe\Funktionstyp\Dateiname

Beispiel:

Standard\Bestellung\EK-B10194 - Telekom-17-E07003AUIJ.pdf

 DBARCHIV.CONTAINER

Gibt den Containernamen an, in welchem das Dokument archiviert wird. Der Wert entspricht DBARCHIV.MUID, so dass alle archivierten Dokumente zu einem Vorgang im gleichen Container abgelegt werden (siehe dazu DBARCHIV.MUID).

Innerhalb des Containers werden die archivierten Dokumente zusätzlich in Containergruppen und darin in Funktionstypen gegliedert organisiert.

Beispiel:

f9720bd04af34fb99af1069bfe0fd0d4\Einkauf\Rechnung\EK-R10073 - amazon-2160091141.pdf

DBARCHIV.CONTAINER = 'f9720bd04af34fb99af1069bfe0fd0d4'
DBARCHIV.CONTAINERGRUPPE = 'Einkauf'
DBARCHIV.FUNKTIONSTYP = 'Bestellung'

DBARCHIV.CONTAINERGRUPPE

Ein Container wird zusätzlich in Containergruppen aufgeteilt, um Dokumente bereichsbezogen archivieren zu können. Im vorigen Beispiel wurde das Dokument in der Containergruppe "Einkauf" archiviert.

DBARCHIV.FUNKTIONSTYP

Innerhalb einer Containergruppe werden Dokumente zusätzlich in sog. Funktionstypen zusammengefasst und archiviert. Im vorigen Beispiel wurde das Dokument innerhalb der Containergruppe "Einkauf" in den Funktionstyp "Bestellung" einsortiert.

DBARCHIV.KURZBESCHREIBUNG

 Speichert einen beliebigen Text, der das archivierte Dokument beschreibt.

DBARCHIV.STICHWORTE

Speichert beliebige Stichworte zu dem archivierten Dokument.

DBARCHIV.QUELLPFAD

Dateiname inkl. vollständigem Pfad des zu archivierenden Dokumentes.

Weitere Infos über dieses wichtige Feld entnehmen Sie bitte der Beschreibung der Befehle "store" und "modify".

isential

Verwendet die direkte ISEntial-Schnittstelle. Der Host übergibt lediglich den Feldwert DBARCHIV.UID, mit dessen Hilfe ISEdoc alle anderen Werte aus den damit verbundenen Datensätzen ermittelt.

Folgende Werte (Datenbankfelder) werden über die ISEntial-Schnittstelle an ISEdoc übergeben: 

db_cs:Datenbankverbindungszeichenkette

Gibt die verschlüsselte Verbindungszeichenkette für den Zugriff auf die Datenbank an.

DBARCHIVREF.UID

UID (Unique Identifier wie z. B. UUID oder Microsofts GUID) des übergebenen Datensatzes aus der angegebenen Datenbanktabelle (DBARCHIVREF).

Die meisten Befehle erfordern diese Angabe, da diese einen wesentlichen Teil der Schnittstelle bildet.

Alle Felder des durch die UID angegebenen Datensatzes müssen mit den für den jeweiligen Aufruf notwendigen Werten gefüllt sein. Damit kann ISEdoc einerseits auf den dazugehörigen Datensatz in DBARCHIV und anderseits auf den Datensatz, für den das Dokument gespeichert wird, zugreifen.

Weitere Befehle 

archive_root:Wert

Zeigt auf das zu verwendende Archiv. Hierbei handelt es sich um einen Ordner auf einem Datenträger, der unmittelbar darunter 256 Unterordner zur Ablage der Containerdateien enthält. Die Namen der sich darin befindlichen Ordner sind zweistellig und lauten "00" bis "FF" (hexadezimale Notation).

Pflichtangabe

extract_to:Wert

Zeigt auf den zu verwendenden Speicherort inklusive Dateiname beim Extract-Befehl.

Pflichtangabe bei cmd:extract

print_to:Wert

Zeigt auf den zu verwendenden Drucker beim Print-Befehl. Wenn nicht angegeben wird der Standard-Drucker verwendet.

print_copies:Wert

Gibt die Anzahl Exemplare beim Print-Befehl an. Wenn nicht angegeben wird 1 angenommen.

gui

Wird die Direktive gui angegeben, so startet ISEdoc mit der Benutzeroberfläche, ansonsten arbeitet ISEdoc im Dienstmodus ohne Benutzerinterface.

Sinnvoll bei Befehlen wie: store, modify

no_return_values

Wird die Direktive no_return_values angegeben, so liefert ISEdoc keine Werte an den Host (i. d. R. die rufende Anwendung) zurück.

Bei Verwendung der Textschnittstelle führt diese Direktive dazu, dass ISEdoc beim Beenden die Parameterdatei löscht.

Nehmen Sie Kontakt mit uns auf. Wir beantworten schnell und unkompliziert Ihre Fragen oder Sie vereinbaren einen Besuchstermin bei uns.