Nutzung und Konfiguration des CMIS-Plugins mit VIS.SAX

In diesem Artikel wird beispielhaft die Nutzung des CMIS-Plugins in Verbindung mit dem VIS.SAX-System Schritt für Schritt erklärt.

Inhalt

Voraussetzungen und Vorbereitung

Für die Benutzung der VIS.SAX-Anbindung in formcycle wird das CMIS-Plugin benötigt. Eine detaillierte Übersicht der Funktionsweise und Handhabung des CMIS-Plugins ist hier verfügbar.

Freischaltung/Aktivierung des CMIS-Plugin und Freischaltung der Anbindungsstrecke

Die Aktivierung des CMIS-Plugin für den jeweiligen formcycle-Mandanten und die Domänenfreigabe für die VIS.SAX-Mandanten *[Behördenkürzel]-ref.evasax.fs.sachsen.de* und/oder *[Behördenkürzel]-prod.evasax.fs.sachsen.de*) erfolgt auf Anfrage der jeweiligen Behörde/Einrichtung an die Anwendungsbetreuung der Basiskomponente Formularservice ([email protected]).

VIS.SAX

Um formcycle über CMIS mit VIS.SAX zu koppeln ist es erforderlich, dass ein technischer Benutzer (AD-Konto) in der FS-Domain angelegt wird. Dieser Nutzer muss vom SID für die Basic Authentifizierung freigeschaltet und auf dem VIS.SAX-Mandanten hinzugefügt werden (VIS-Verantwortlicher der Behörde an den Servicedesk des SID per Ticket). Seitens der Behörde gilt es, diesen Nutzer an den Ablagen und Schriftgutobjekttypen so zu berechtigen, dass über die Schnittstelle Schriftgutobjekte im Nutzerkontext dieser Nutzer angelegt oder abgerufen werden können. Der eingerichtete technische Nutzer kann nur Ergebnisse an formcycle zurückliefern auf den er auch berechtigt ist.

CMIS 

Content Management Interoperability Services ist ein offener Standard und erlaubt es herstellerunabhängig eine Anbindung zu DMS-Systemen zu schaffen, wie bspw. zum Verwaltungsinformationssystem VIS.SAX. In CMIS, wie auch in VIS.SAX gibt es ein sogenanntes Dokument. Jedoch bedeuten beide etwas Unterschiedliches. In CMIS ist damit eine Datei gemeint, welche in einem Ordner abgelegt werden kann und den Objekt-Typen „Dokument“ hat. In VIS.SAX handelt es sich dabei um ein Schriftgutobjekt VIS-Dokument.

Zur Klarheit wird in diesem Artikel die Bezeichnung CMIS-Dokument und VIS-Dokument verwendet, um Verwechslungen zu vermeiden.

Nach der Installation des CMIS-Plugins steht in den Systemeinstellungen sowie für berechtigte Mandanten ein neuer Menüeintrag "CMIS-Verbindungen" zur Verfügung. Es ist möglich, mehrere CMIS-Verbindungen zu bestehenden Systemen mit CMIS-Anbindung zu konfigurieren , hierdurch lassen sich zum Beispiel verschiedene Berechtigungsrollen in VIS.SAX abbilden.

Für die Konfiguration der CMIS-Anbindung von VIS.SAX werden folgende Daten benötigt:

• Server-Url für einen der Verbindungstypen AtomPub oder Browser
• Authentifizierungsdaten für VIS.SAX (von dem Nutzer oder den Nutzern, für die die Basic-Authentifizierung eingerichtet wurde, siehe Voraussetzungen)
• Ggf. Verbindungsdaten für einen Proxy-Server 

Für die Authentifizierung benötigt der Benutzer eine Basic-Auth-Freigabe. Dies ist bei der Beantragung des VIS.SAX-Zugangs zu berücksichtigen.

Wurden alle für den Verbindungsaufbau notwendigen Daten eingegeben, kann über den Button „Verbindung testen“ sichergestellt werden, ob die Verbindung zum VIS.SAX-System in formcycle hergestellt werden kann.

Über den Button „CMIS-Objekte laden“ kann abschließend noch einmal sichergestellt werden, dass auch alle Ordner-Objekte angezeigt werden, in denen Ordner bzw. Dateien angelegt werden sollen. 

Wie in den Voraussetzungen beschrieben, liefert das System nur die Objekte oder Listeneinträge zurück, auf denen der Nutzer, der in den CMIS-Verbindungsdaten angegeben wurde auch berechtigt ist.

2. Schritt – Verbindung in Workflow-Aktion auswählen

Nach der Installation des Plugins sollte die Workflow-Aktion "CMIS-Objekt anlegen" im Workflow-Designer eines Formulars verfügbar sein. Diese kann anschließend in den Workflow hineingezogen werden, um die Konfiguration für das Anlegen eines CMIS-Objekts vorzunehmen.

In den Verbindungseinstellungen muss eine bestehende CMIS-Verbindung zum VIS.SAX-System ausgewählt werden, welche bereits im ersten Schritt konfiguriert wurde. Anschließend wird eine URL angezeigt, um zu überprüfen, ob die korrekte Verbindung ausgewählt wurde.

Falls der Verbindungsaufbau nicht im ersten Schritt schon überprüft wurde, kann über den Button „Verbindung testen“ die Verbindung erneut getestet werden, um sicherzustellen, dass ein Verbindungsaufbau aus formcycle möglich ist. Sollten Fehlermeldungen auftreten, überprüfen Sie bitte zuerst, ob die Konfiguration aus dem ersten Schritt ordnungsgemäß durchgeführt wurde.

3. Schritt – VIS-Akte, VIS-Vorgang oder VIS-Dokument anlegen

Objekt-Typ auswählen

Um eines der drei Schriftgutobjekte zu erstellen, müssen Sie in den Objekteinstellungen den Objekttyp "Ordner" auswählen.

Objekt-Typ-ID auswählen

Danach muss die ID eines VIS.SAX-Schriftgutobjekts im Eingabefeld „Objekt-Typ-ID“ eingegeben werden. Hier wird der genaue Typ des Schriftgutobjekts festgelegt.

Durch Eingabe der ID oder Namen eines Schriftgutobjekts wird per Autovervollständigung mögliche Typen vorgeschlagen. Die angezeigten IDs sind die VIS.SAX internen Listen-IDs, siehe hierzu auch Verfahrensbeschreibung VIS.SAX. Soweit diese nicht bekannt sind, wenden Sie sich bitte an den VIS-Verantwortlichen der Behörde.

Wenn Sie eine ID ausgewählt haben, können Sie durch Bewegen des Mauszeigers über das Info-Symbol Informationen zum Namen des Schriftgutobjekts erhalten. Wenn das ausgewählte Schriftgut ein Untertyp ist, wird auch der zugehörige übergeordnete Typ angezeigt.

Wenn eine Objekt-Typ-ID vom Schriftgutobjekt "Akte" ausgewählt wird, ist die Objekt-Eigenschaft "vis:aktpl1_schl" (Aktenplankennzeichen) für den entsprechenden Akten-Typen zu konfigurieren.

Beispiel: Bitte geben Sie entweder „-51“ oder „Antrag“ ein, um die Option „-51 (Antrag)“ anzeigen zu lassen. Sobald Sie darauf klicken, wird die ID „-51“ im Eingabefeld angezeigt und der Name „Antrag“ sowie das übergeordnete Schriftgutobjekt „Eingang“ werden am Info-Symbol angezeigt. "Eingang" ist ein Untertyp des Schriftgutobjekts "VIS-Dokument".

Zielordnerpfad auswählen

Klicken Sie auf den Ordner-Button, um einen Dialog mit der Ordnerstruktur der VIS.SAX-Verbindung zu öffnen. Wählen Sie einen Ordner aus, in dem das Objekt auf dem VIS.SAX-System erstellt werden soll. Rechts daneben erhalten Sie relevante Informationen zum ausgewählten Objekt, wie bspw. die Objekttyp-ID des bestehenden CMIS-Objekts. Durch Klicken auf das Kopier-Symbol wird automatisch der entsprechende Ordnerpfad zum selektierten Ordner in das zugehörige Eingabefeld kopiert.

Bei der Auswahl des Zielordnerpfades sollten Sie darauf achten, dass der ausgewählte Ordner je nach vorherigem selektierten Schriftgutobjekt im Eingabefeld "Objekt-Typ-ID" passend ist und sich als übergeordnetes Schriftgutobjekt eignet. Es ist wichtig, die Reihenfolge VIS-Akte => VIS-Vorgang => VIS-Dokument einzuhalten, um die Aktion fehlerfrei ausführen zu können.

Um den Ordnerpfad eines im Workflow vorher konfigurierten CMIS-Objekt weiter zu nutzen kann der Rückgabe-Wert "objectPath" der CMIS-Workflow-Aktion in einer folgenden CMIS-Workflow-Aktion weiter genutzt werden. Der Platzhalter des Rückgabe-Wert gibt den internen Pfad eines erstellten Ordners zurück.

Beispiel: Wenn Sie als Schriftgutobjekt im Eingabefeld Objekt-Typ-ID "VIS-Dokument" ausgewählt haben, sollten Sie einen Ordner als Zielordnerpfad wählen, der das Schriftgutobjekt "VIS-Vorgang" darstellt.

Es wurde eine CMIS-Workflow-Aktion konfiguriert mit dem Zweck, einen Ordner-Objekt vom Schriftgutobjektstyp "VIS-Vorgang" anzulegen. Die Workflow-Aktion heißt "VIS-Vorgang anlegen". 

In einer nachfolgenden CMIS-Workflow-Aktion "VIS-Dokument in VIS-Vorgang anlegen" kann nun der Zielordnerpfad "[%$VIS-Vorgang in VIS-Akte anlegen.RESULT.objectPath%]" verwendet werden, um das "VIS-Dokument" in dem zuvor konfigurierten Ordner abzulegen.

"Bestehenden Ordner zurückgeben" aktivieren (Optional)

Wenn im spezifizierten Zielordner bereits ein Ordner existiert, dessen Name mit dem im Feld "Objektname" eingegebenen Namen übereinstimmt, wird der Ordnerpfad des existierenden Ordners als Aktionplatzhalter "objectPath" zurückgegeben. In diesem Fall erfolgt keine Erstellung eines neuen CMIS-Ordner-Objekts. Stattdessen wird das vorhandene CMIS-Ordner-Objekt bereitgestellt und kann über den Aktionplatzhalter "objectPath" für weitere Aktionen verwendet werden. Sollte jedoch kein existierender Ordner mit dem angegebenen Objektnamen gefunden werden, wird ein neuer CMIS-Ordner erstellt. Diese Funktionalität ermöglicht eine effiziente Nutzung bestehender Ordner-Objekte ohne Duplikation von Ordnern im System und gewährleistet gleichzeitig die Möglichkeit zur Erstellung neuer Ordner, falls erforderlich.  

Benennung des Objekts und Konfiguration der Objekt-Eigenschaften

Wenn eine Objekt-Typ-ID vom Schriftgutobjekt "Akte" ausgewählt wird, ist die Objekt-Eigenschaft "vis:aktpl1_schl" (Aktenplankennzeichen) für den entsprechenden Akten-Typen zu konfigurieren.

Für die Benennung des Schriftgutobjekts kann das Eingabefeld „Objekt-Name“ nicht verwendet werden, sondern die Objekt-Eigenschaft "vis:kurzbez" (Kurzbezeichnung).  Außer die Option "Bestehenden Order zurückgeben" ist aktiviert, dann sollte das Eingabefeld "Objekt-Name" und die Objekt-Eigenschaft "vis:kurzbez" befüllt werden.

Objekt-Eigenschaften können über die Eigenschaftstabelle konfiguriert werden. Durch Klicken auf die Hinzufügen-Schaltfläche  in der oberen rechten Ecke der Objekt-Eigenschaftstabelle wird ein Dialogfeld mit allen verfügbaren Objekt-Eigenschaften für das ausgewählte Schriftgutobjekt-ID im Eingabefeld Objekttyp-ID angezeigt.

Bitte wählen Sie aus der Tabelle alle Eigenschaften und Metadaten aus, die für das anzulegende Objekt relevant sind. Verwenden Sie das Feld "vis:kurzbez", um das Objekt zu benennen. Sie können die Tabelle nach Eigenschaften filtern, um die Suche zu erleichtern. 

Klicken Sie auf den Button "Aktualisieren", um alle ausgewählten Eigenschaften in die Tabelle einzufügen. Abschließend müssen die Werte für die ausgewählten Eigenschaften eingetragen werden. Platzhalter können genutzt werden, um bspw. Eingabedaten aus einem Formular zu ersetzen.

4. Schritt - Datei anlegen

Um nun das Anlegen einer Datei im VIS.SAX-System über CMIS zu konfigurieren, erstellen Sie im Workflow eine neue Aktion vom Typ „CMIS-Objekt anlegen“.

Objekt-Typ auswählen

Wählen Sie den Objekttyp "Dokument" aus, um eine Datei über CMIS im VIS.SAX-System anzulegen. Dabei handelt es sich um ein CMIS-Dokument.

Objekt-Typ-ID auswählen

Für das Anlegen einer Datei in VIS.SAX über CMIS sollte immer die Objekt-Typ-ID "vis:document" gewählt werden, da diese allgemein zur Identifikation von Dateien verwendet wird.

Objekt-Namen festlegen

Geben Sie einen individuellen Namen ein oder lassen Sie das Feld leer, um den Namen der Datei ohne Dateiendung als Objekt-Namen zu verwenden.

Endung anhängen

Diese Option kann aktiviert werden, um die Dateiendung an den Objekt- oder Dateinamen anzufügen (beispielsweise *.pdf, *.docx, *.png usw.).

Automatische Versionsnummer hinzufügen

Aktivieren Sie diese Option, um die Vergabe identischer Objektnamen zu ermöglichen. Bei gleichen Namen wird eine Versionsnummer an den Namen angehängt. Zum Beispiel wird „Datei.pdf“ zu „Datei (1).pdf“, wenn „Datei.pdf“ bereits am konfigurierten Speicherort vorhanden ist.

Zielordnerpfad auswählen

Über den Ordner-Button kann der Dialog geöffnet werden, um den Zielordnerpfad festzulegen.  Beim Erstellen einer Datei ist es wichtig, einen Ordner auszuwählen, der das Schriftgutobjekt "VIS-Dokument" oder eines seiner Untertypen repräsentiert.  Nur in diesem Fall kann eine Datei erfolgreich angelegt werden. 

Um den Ordnerpfad eines im Workflow vorher konfigurierten CMIS-Objekt weiter zu nutzen kann der Rückgabe-Wert "objectPath" der CMIS-Workflow-Aktion in einer folgenden CMIS-Workflow-Aktion weiter genutzt werden. Der Platzhalter des Rückgabe-Wert gibt den internen Pfad eines erstellten Ordners zurück.

Beispiel: Es wurde eine CMIS-Workflow-Aktion "VIS-Dokument anlegen" konfiguriert, welche ein Ordner-Objekt vom Schriftgutobjektstypen "VIS-Dokument" anlegt. 

In einer folgenden CMIS-Workflow-Aktion "Datei in VIS-Dokument anlegen" kann nun als Zielordnerpfad "[%$VIS-Dokument anlegen.RESULT.objectPath%]" eingetragen werden, um die Datei im vorher konfigurierten Ordner abzulegen.

Datei-Ressourcen auswählen

Wählen Sie eine oder mehrere Dateien aus, zum Beispiel aus vorherigen Aktionen oder Upload-Elementen im Formular. Hierbei können auch wiederholte Upload-Elemente selektiert werden, womit alle hochgeladenen Dateien am Upload-Element über die Workflow-Aktion angelegt werden.

Beispiel-Konfiguration für das Anlegen einer Datei in einem Ordner vom Schriftgutobjekttyp "VIS-Dokument".

5. Schritt - Ausführen der Aktion & Fehleranalyse

Ausführen der Aktion

Nach erfolgreicher Übermittlung des Formulars können Sie in der Ordnerstruktur der Verbindungskonfigurationsoberfläche prüfen, ob die erstellten Objekte auch in VIS.SAX vorhanden sind.  Auf diese Weise wird sichergestellt, dass die Aktion korrekt ausgeführt wurde

Fehlerauswertung im Workflow

Verwenden Sie die Fehlercode-Platzhalter der CMIS-Workflow-Aktion, um CMIS-Aktionsfehler im Workflow auszuwerten. Weitere Informationen zur Auswertung von Workflow-Fehlern finden Sie hier.

Fehleranalyse

Überprüfen Sie das Prozess-Protokoll auf mögliche Fehler. Die Details enthalten eventuell Hinweise der VIS.SAX-Anbindung, wodurch der Fehler ausgelöst wurde.

Bitte beachten Sie, dass das VIS.SAX System aufgrund routinemäßiger Wartungsarbeiten vorübergehend nicht verfügbar sein kann. Dies könnte sich auf die Zugänglichkeit sowie das Übertragen von Dateien und das Anlegen von Ordnern auswirken. Bitte informieren Sie sich bei Ihrem VIS.SAX-Ansprechpartner über Ausfälle und Wartungsarbeiten.