Connector für M-Files in Applikationen

Modul Applikationen

1. Verbindung anlegen

Legen Sie zuerst eine Verbindung zum M-Files-System an.

2. Datenfelder anlegen

Für das Speichern von Metadaten und Dokumenten über Intrexx in M-Files wird eine Intrexx-Datengruppe verwendet. Fremddatengruppen werden zurzeit nicht vom Connector unterstützt. Die folgenden Datenfelder werden in dieser Datengruppe mindestens benötigt:

3. Dateidatenfeld erstellen

Nachdem alle Felder für die M-Files-Metadaten in der Datengruppe angelegt wurden, kann das Datei-Datenfeld für die M-Files-Dokumente erstellt werden.

Es ist zwar grundsätzlich möglich, mehrere M-Files-Dateifelder zu erstellen, empfohlen wird aber nur eines pro Datengruppe, da sonst die Zuordnung der Metadaten unübersichtlich wird.




Wählen Sie hier den Datei-Datentyp aus und klicken Sie dann auf den Link "mehr…".



Hier kann der de.uplanet.lucy.server.mfiles.connector.MFilesFileHandler ausgewählt werden. Klicken Sie hier und in dem Dialog, in dem Sie den Datentyp ausgewählt haben, auf OK.



Öffnen Sie den Eigenschaftendialog des neu angelegten Datei-Datenfeldes.

4. Eigenschaften - Reiter Allgemein




Alle Informationen zu diesen Einstellungen finden Sie hier.

5. Eigenschaften - Reiter Feldzuordnung


5.1. Pflichtfelder

Diese Metadaten werden, um ein Dokument bzw. Objekt erfolgreich in M-Files erstellen oder ändern zu können, zwingend benötigt: Je nach verwendeter Dokumentenklasse können weitere Felder in M-Files als Pflichtfelder definiert sein.

5.2. Optionale Felder

Diese Felder sind optional, aber empfohlen. Wie Sie die Feldzuordnung herstellen und weitere Informationen zum Thema finden Sie hier.

5.3. Zuordnung von benutzerspezifischen Werten

Neben Datenfeldern können M-Files-Feldern auch benutzerdefinierte Werte zugewiesen werden, z.B., wenn für das M-Files-Pflichtfeld Klasse immer der gleiche Wert verwendet werden soll.

Wert hinzufügen
Öffnet einen Dialog, in dem ein benutzerdefinierter Wert erstellt werden kann.



Hier kann nun z.B. der statische Wert 10 erstellt und dem M-Files-Feld Klasse in der Feldzuordnung zugewiesen werden. Auch berechnete Datumswerte oder Systemwerte wie z.B. der aktuelle Intrexx-Benutzer können als benutzerdefinierter Wert zugeordnet werden. Ein weiteres Beispiel wäre die Generierung einer GUID zur Laufzeit als eindeutige Datensatz-ID für Intrexx und M-Files. Berechnete Werte werden in der Regel nicht in Intrexx-Datenfeldern, sondern nur in M-Files-Feldern gespeichert. Für bestimmte Zwecke muss ein statischer Wert auch in einem Intrexx-Datenfeld gespeichert werden, z.B., wenn die ID-Ermittlung aus Intrexx eingestellt wurde und eine GUID dafür generiert werden soll. Diese wird hier als benutzerdefinierter Wert eingestellt und einem eigens dafür angelegten M-Files-Feld zugewiesen. Da diese GUID später auch in Intrexx zur Verfügung stehen muss, um das entsprechende Objekt in M-Files zu ermitteln, werden Sie nach der Zuweisung des Wertes an ein M-Files-Feld automatisch gefragt, ob der Wert auch in ein Intrexx-Datenfeld gespeichert werden soll.

5.4. Zuordnung von Auswahllisten




M-Files-Felder für Wertelisten haben in M-Files den Lookup- bzw. MultiSelectLookup-Datentyp (für Listen mit Mehrfachauswahl). Jeder Eintrag einer Werteliste in M-Files hat dabei eine eindeutige ID (Typ Integer), die letztendlich im M-Files-Objekt gespeichert wird. Wenn ein Intrexx-Datenfeld oder ein benutzerdefinierter Wert einem solches M-Files-Feld zugeordnet wird, ist zu beachten, dass über den Wert in Intrexx der entsprechende Eintrag der Auswahlliste in M-Files ermittelt werden kann. Wird als Zuweisung ein Intrexx-Datenfeld mit Integer-Typ zugeordnet, so muss sichergestellt werden, dass es in der M-Files-Werteliste einen entsprechenden Eintrag mit diesem ID-Wert gibt. Alternativ kann der Eintrag in der Liste über den Anzeigewert ermittelt werden.

Optionen
Ist ein Lookup- bzw. MultiSelectLookup-M-Files-Feld in der Feldzuordnung markiert, so öffnet ein Klick auf die Schaltfläche, die Sie in der Optionen-Spalte finden, einen Dialog, in dem eingestellt werden kann, wie die Werte von Wertelisten in M-Files ermittelt werden. Wird der Werteliste z.B. ein String-Feld zugewiesen, so muss der darin gespeicherte Wert einem Anzeigewert in der M-Files-Werteliste entsprechen. Dabei ist die Groß-/Kleinschreibung zu beachten. Welche Strategie hier gewählt wird, hängt vom gewünschten Anwendungsfall ab. Sind die IDs der Listeneinträge in M-Files bekannt, so sollte der Eintrag über die ID ermittelt werden. Ist dies nicht der Fall, bietet sich die Ermittlung über den Anzeigewert an. In der Regel werden die Werte über die ID ermittelt.

6. Eigenschaften - Reiter Authentifizierung




Hier kann definiert werden, welcher Portalbenutzer für die Authentifizierung beim Zugriff auf den M-Files-Vault ermittelt werden soll. Alle weiteren Informationen finden Sie hier.

7. M-Files-Datengruppen-Handler

Sobald einer Intrexx-Datengruppe ein Dateifeld für M-Files hinzugefügt und dieses konfiguriert wurde, wird automatisch die datahandler-Klasse in den Expert-Attributen der Datengruppe auf 
de.uplanet.lucy.server.mfiles.connector.rtdata.RtDataGroupTableMFiles
geändert. Dies kann auch nachträglich vorgenommen werden. Die M-Files spezifische Datengruppen-Handler-Klasse ist optional, bietet aber zusätzliche Funktionalität im Zusammenspiel von Intrexx und M-Files. So wird eine automatische Synchronisation der Metadatenwerte aus M-Files vorgenommen, sobald ein M-Files-Datensatz auf einer Intrexx-Ansichts- oder Eingabeseite geladen wird. Damit wird gewährleistet, dass ein Intrexx-Portalbenutzer stets die aktuellen Metadaten aus M-Files angezeigt bekommt. Unter Umständen kann es nämlich vorkommen, dass Metadaten in M-Files geändert wurden und in Intrexx noch die vorherigen Werte gespeichert sind.

8. M-Files in Portal-Applikationen

8.1. Authentifizierung

Beim ersten Zugriff auf eine Portal-Applikation mit einer Datengruppe, die M-Files-Datei-Datenfelder enthält, wird der Benutzer aufgefordert, sich am M-Files-Vault anzumelden. Pro Sitzung und M-Files-Vault ist das nur einmal erforderlich. Sollte die Integrierte Windows-Authentifizierung für das Portal eingestellt sein, wird der Benutzer automatisch beim ersten Zugriff angemeldet. Eine Anmeldung wird nicht benötigt, wenn im Dateifeld der Datengruppe ein statischer Benutzer für die M-Files Authentifizierung hinterlegt wurde. Nach erfolgreicher Authentifizierung kann über die Intrexx-Applikation auf M-Files-Daten zugegriffen werden.

8.2. M-Files-Dateien in Ansichtstabellen

M-Files-Datei-Datenfelder können in Ansichtstabellen platziert werden, um Dateien direkt aus Tabellen zu öffnen. In der Standardeinstellung werden aus Performancegründen jedoch keine Dateien aus M-Files in Datei-Datenfeldern angezeigt, wenn sie in einer Ansichtstabelle dargestellt werden. Mit der Option Dateien aus M-Files auch in Ansichtstabellen anzeigen in der Datei-Datenfeld-Konfiguration kann die Anzeige aktiviert werden. Sollen Dokumente direkt aus Tabellen heraus heruntergeladen werden können, muss dies in den Eigenschaften des Datei-Datenfeldes in der Ansichtstabelle aktiviert werden.



Bitte beachten Sie, dass keine Thumbnails für M-Files Dateien angezeigt werden können, weil diese nicht auf dem Intrexx-Portalserver, sondern nur in M-Files vorgehalten werden. Somit können auch keine Vorschaubilder von Intrexx generiert werden.

8.3. M-Files-Dateien auf Ansichtsseiten

M-Files-Dateien werden auf Ansichtsseiten über das Dateiauswahl Ansicht-Element dargestellt.



Auch hier kann ein Download der Dateien ermöglicht werden.

8.4. M-Files-Dateien auf Eingabeseiten

Mit dem Dateiauswahl-Element auf Eingabeseiten können M-Files-Dateien und -Dokumente über Intrexx hochgeladen, geändert und in M-Files gespeichert werden. Es stehen dabei alle Funktionen von Standard-Intrexx-Datei-Datenfeldern zur Verfügung.



Neben dem Freischalten von Downloads kann im Eigenschaftendialog auf dem Reiter Optionen auch das Upload-Verhalten definiert werden. Grundsätzlich werden neue Dateien bei M-Files-Mehrfachdateifeldern den vorhandenen Dateien hinzugefügt. Es ist aber auch möglich, Dateien zu ersetzen. Außerdem kann eingestellt werden, wie viele Dateien maximal pro Dateifeld gespeichert werden dürfen. Auch die maximale Größe einer Datei kann vorgegeben werden. Daneben gibt es noch erweiterte Funktionen zum Upload von Dateien, die sich auf das Verhalten der Kontrolle im Portal auswirken.



Im Browser können Dateien per Drag & Drop auf die Dateikontrolle gezogen und damit automatisch auf den Intrexx-Server hochgeladen werden. Beim Speichern der Eingabeseite werden die hochgeladenen Dateien zusammen mit den Informationen in den Metadaten an den M-Files Server übertragen. Die neue Objekt-ID und die Version werden in Intrexx gespeichert. Bestehende Dateien können hier mit Klick auf das Löschen-Symbol in M-Files gelöscht werden.

Die Datei wird damit nicht physisch gelöscht. Es wird lediglich eine neue Version des Dokumentenobjekts in M-Files erstellt, die die entfernte Datei nicht mehr enthält. Bei Objekten mit Single File-Typ können Dateien aktualisiert bzw. ersetzt werden, in dem zunächst eine bestehende Datei entfernt und dann die neue Datei hochgeladen wird.

8.5. M-Files-Dateien in Auswahllisten

Um dem Portalbenutzer die Pflege der M-Files-Metadaten so einfach wie möglich zu machen, bietet es sich an, für Wertelisten in M-Files identische Auswahllisten auf Eingabeseiten in Intrexx anzulegen und als Speicherwert entweder die ID oder den Anzeigewert zu wählen. Dementsprechend ist dann die Werteermittlung (ID/Anzeigewert) für das Metadatenfeld einzustellen. Die IDs und Anzeigewerte von M-Files-Auswahllisten können über das M-Files-Server-Administrationstool ermittelt werden. Öffnen Sie dazu den gewünschten Vault und darunter den Punkt "Value Lists" unterhalb von "Metadata Structure (Flat View)". Es werden alle Wertelisten im rechten Bereich angezeigt. Über das Kontextmenü Contents einer Liste werden die Einträge und deren ID der Auswahlliste angezeigt. Das folgende Beispiel zeigt die Anzeigewerte und deren ID der Classes-Werteliste in M-Files.



In M-Files werden die Einträge für Auswahllisten in den meisten Fällen automatisch über in Beziehung stehende Objekte generiert, z.B. wenn in einer Kunden-Auswahlliste alle M-Files Objekte vom Typ Kunde als Einträge aufgelistet werden. Diese Einträge können Sie über die Metadata Structure (Hierarchical View) einsehen.



Daneben gibt es auch die Möglichkeit, Auswahllisten per SQL-Abfragen aus externen Systemen zu befüllen. Dies bietet sich an, wenn die Einträge aus einer Intrexx-Datengruppe kommen sollen. So kann eine automatische Synchronisation zwischen Intrexx und M-Files sichergestellt werden. Weitere Informationen dazu finden Sie in der M-Files-Dokumentation. In Intrexx kann nun auf einer Eingabeseite eine Auswahlliste erstellt werden, deren Einträge die einer M-Files Werteliste reflektieren. Dazu können die Werte aus anderen Applikation, Referenzen oder benutzerspezifisch definiert werden. Das folgende Beispiel zeigt, wie die M-Files-Werteliste "Customer" auf einer Intrexx Eingabeseite nachgebildet wird. In diesem Fall werden die Anzeigewerte als Speicherwerte benutzt, was bedeutet, dass das zugewiesene Metadaten-Feld in der Datengruppe ein String-Typ sein muss und in der M-Files-Dateifeld-Konfiguration die Ermittlung des Listeneintrags über den Anzeigewert erfolgen muss.

9. Metadaten-Aktualisierung

Da Dokumente und Dateien nur im M-Files-Vault gespeichert und vorgehalten werden, sind diese stets auf dem aktuellen Stand, wenn darauf über Intrexx zugegriffen wird. Etwas anders verhält es sich mit den Metadaten eines Dokuments. Diese werden sowohl in Datenfeldern der Intrexx-Datengruppe als auch in M-Files gespeichert. Das hat den Vorteil, dass auch in Intrexx nach Metadaten gesucht und auf Datensätze zugegriffen werden kann, ohne dass jedes Mal ein Zugriff auf den M-Files-Server stattfinden muss. Der Nachteil dieses Ansatzes ist, dass sich mit der Zeit die Metadaten eines Dokuments in M-Files ändern können, während in Intrexx noch die alten Werte gespeichert sind.

Da Intrexx über Änderungen an Metadaten nicht automatisch von M-Files informiert werden kann, werden Metadaten in Intrexx aktualisiert, sobald ein Datensatz auf einer Ansichts- oder Eingabeseite geladen wird, der ein M-Files-Dateifeld beinhaltet. Beim Speichern der Seite werden die aktualisierten Metadaten wieder in Intrexx gespeichert. Wenn Felder auch in M-Files aktualisiert werden sollen, muss die Object-ID als Eingabefeld auf Eingabeseiten aufgenommen werden.

Mit Prozessen können Metadaten zwischen Intrexx und M-Files stets synchron gehalten werden.

10. Suche in M-Files-Dokumenten

Dokumente und Dateien in M-Files-Datenfeldern werden nur auf dem M-Files Server aufbewahrt. Dadurch ist es für die Intrexx-Suchmaschine nicht möglich, die Inhalte der Dateien zu indexieren, um sie für Suchanfragen in Intrexx verfügbar zu machen. Es kann lediglich nach Metadaten, die in Intrexx-Datengruppen gespeichert sind, gesucht werden. Die M-Files-Webservice-Schnittstelle bietet die Möglichkeit, über die M-Files-Volltextsuche nach Dokumenten in M-Files zu suchen. Die Ergebnisse müssen dann entsprechend für Intrexx aufbereitet werden, so dass sich bei Klick auf einen Treffer das Dokument im M-Files-Web-Access-Client öffnet oder der entsprechende Datensatz via Filter in Intrexx mit der Verknüpfung zum M-Files-Dokument geöffnet wird.

10.1. Intrexx Suche

Um in Intrexx gespeicherte Metadaten eines Dokuments in M-Files zu suchen, können Sie wie gewohnt die Suche in einer Applikation konfigurieren. Erstellen Sie dazu eine Suchkonfiguration und wählen Sie die Metadaten-Felder in der M-Files-Datengruppe aus, die von der Suchmaschine indexiert werden sollen. Anschließend können M-Files-Datensätze über die Suchfunktion in Intrexx nach Metadaten durchsucht werden. Ein weiterer Ansatz ist die Suche über dynamische Filter in Intrexx-Applikationen. Dabei werden Filter auf Ansichtstabellen definiert, die entsprechend Datensätze gemäß den Werten in den Metadaten-Feldern der Intrexx-Datengruppe filtern.

10.2. M-Files Volltextsuche

Soll neben den Metadaten auch in den Dokumenten nach Stichwörtern gesucht werden, bietet sich die M-Files-Volltextsuche an. Dabei kann direkt in Intrexx nach in Intrexx verwalteten M-Files-Dokumenten gesucht und die Treffer angezeigt werden. Es bietet sich auch die Möglichkeit, im Portal nach Dokumenten in M-Files zu suchen, die nicht über Intrexx erfasst wurden. Für den letzteren Fall benötigen die Portalbenutzer auch Zugriff auf den M-Files Web Access Client, um gefundene Dokumente darin zu öffnen. Im Folgenden wird die Umsetzung beider Ansätze beschrieben.

10.2.1. Volltextsuche über Intrexx verwaltete M-Files Dokumente

Im folgenden Beispiel soll in M-Files-Dokumenten gesucht werden, für die es einen entsprechenden Datensatz in einer M-Files-Datengruppe gibt. Dazu erstellen Sie eine Ansichtstabelle auf die M-Files-Datengruppe für die Suchergebnisse. Zudem wird ein Eingabefeld für den Suchausdruck benötigt.



Wechseln Sie im Eigenschaftendialog der Ansichtstabelle auf den Reiter Abhängigkeiten.



Fügen Sie dort eine Abhängigkeit hinzu. Klicken Sie im nächsten Dialog auf Ereignis hinzufügen und wählen Sie als Kontrolle hier z.B. die Suchen-Schaltfläche mit dem onclick-Ereignis aus. Klicken Sie dann auf im Eigenschaftendialog der Abhängigkeit auf Filter im Expertmodus bearbeiten. Kopieren Sie das folgende XML-Fragment in den Editor in das <filter></filter> Element: 
de.uplanet.lucy.server.mfiles.connector.rtdata.RtDataGroupTableMFiles
<exp op="" type="in">
	<arg content="DAD4BDABD500CD3710605887224DBD48812B22D3" type="fieldguid"/>
	<arg content="de.uplanet.lucy.server.mfiles.connector.rendering.MFilesSearchFilterHandler" defaultReturnValue="0" mfilesCfgGuid="FDD463A8CFBE240F3F23CD8249418B2DE20321F5" mfilesVaultGuid="{C12E1F56-D69B-4F04-8EC8-BAE18B99532B}" objectProperty="ID" returnType="integer"searchControlName="textcontrol52ACE8C8" singleton="false"type="handlerClass"/>
</exp>
Passen Sie dann die Filter Argumente entsprechend Ihrer Applikation an:

10.2.2. Volltextsuche über nicht mit Intrexx verwaltete M-Files Dokumente

Über die M-Files-REST-Web-Service-Schnittstelle lassen sich auch in Groovy-Action-Handlern und Velocity-Templates nach M-Files-Dokumenten suchen und die Ergebnisse in Intrexx darstellen. Dazu sind die Aufrufe der Suche und die Darstellung der Ergebnisse selbst zu programmieren, da diese immer anforderungsspezifisch sind.

10.3. Suche über M-Files Views

Entsprechend der Volltextsuche ist es auch möglich, auf Basis bestehender Views in M-Files zu suchen. Dazu gehen Sie genau so vor wie bei der Volltextsuche. Lediglich ein anderer Filter-Handler kommt für die Suche per Views zum Einsatz: 
<exp op="" type="in">
	<arg content="DAD4BDABD500CD3710605887224DBD48812B22D3" type="fieldguid"/>
	<arg content="de.uplanet.lucy.server.mfiles.connector.rendering.MFilesViewSearchFilterHandler" defaultReturnValue="0" mfilesCfgGuid="FDD463A8CFBE240F3F23CD8249418B2DE20321F5" mfilesVaultGuid="{C12E1F56-D69B-4F04-8EC8-BAE18B99532B}" objectProperty="ID" returnType="integer" viewPathControlName="textcontrol52ACE8C8" singleton="false"type="handlerClass"/>
</exp>
Die Bedeutung der Filter-Argumente sind die gleichen wie für die Volltextsuche mit Ausnahme des viewPathControlName-Arguments. Tragen Sie hier entweder den Namen einer Eingabekontrolle ein, die den Pfad der zu verwendenden M-Files-View enthält, oder einen fixen View-Path, so dass die Suche immer über die gleiche View ausgeführt wird. Der View-Path setzt sich aus der ID der Views in M-Files zusammen. Soll z.B. über die MyProposals-View in M-Files gesucht werden, so muss zunächst die ID dieser View in M-Files ermittelt werden. Öffnen Sie dazu im M-Files Client die Eigenschaften der View.



Die ID der View finden Sie im Titel des Eigenschaftendialogs. Um diese View in Intrexx zu verwenden, sähe der View-Path wie folgt aus:

V110

Soll über eine View-Hierarchie gesucht werden, könnte folgender View-Path verwendet werden:

V110/V111

Alternativ können auch andere View-Path-Ausdrücke verwendet werden. Weitere Informationen dazu finden Sie in der M-Files-Web-Service-Dokumentation.

11. Weitere Informationen

Connector für M-Files
M-Files-Daten konsumieren
M-Files in Prozessen
Export / Import
Troubleshooting