Connector for M-Files in applications

Applications module

1. Create connection

To start with, create a connection to the M-Files system.

2. Create data fields

To save metadata and documents in M-Files via Intrexx, an Intrexx data group is required. External data groups are currently not supported by the Connector. At least the following fields are required in the data group:

3. Create file data field

After you have created all fields for the M-Files metadata in the data group, the file field for M-Files documents can be created.

Though it is fundamentally possible to create multiple M-Files file fields, it is recommended to only use one per data group, otherwise it can become difficult to keep an overview of the metadata assignments.




Select the File data type and then click on "more...".



Here, select the handler "de.uplanet.lucy.server.mfiles.connector.MFilesFileHandler" and confirm this dialog and the next dialog with OK.



Open the properties dialog of the new file field.

4. Properties - General tab




Click here for more information about settings in this dialog.

5. Properties - Data field mapping tab


5.1. Mandatory fields

The following metadata is required to create or edit a document or object in M-Files: Additional fields can be defined in M-Files as mandatory fields, depending on the document class in use.

5.2. Optional fields

These fields are optional but recommended. How to map fields and more information about this tab can be found here.

5.3. Assign user-defined values

In addition to data fields, user-defined values can also be assigned to M-Files fields, if for example, the same value should always be used for the M-Files Class mandatory field.

Add value
Opens a dialog where a user-defined value can be defined.



Here for example, a static value of 10 can be created and assigned to the M-Files Class mandatory field on the Data field mapping tab. In the same way, calculated date values or system values like the current Intrexx user can be created. An additional example would be the generation of a GUID at runtime as a unique data record ID for Intrexx and M-Files. For certain purposes, it is necessary to also save a static value to an Intrexx field. This is the case, for example, if From Intrexx was selected for "Evaluation of the ID", and a GUID needs to be generated for that purpose. This is defined as a GUID value and an M-Files field created for this is assigned to it. Since this GUID will need to be available for use in Intrexx later as well, in order to determine the corresponding object in M-Files, you will be automatically asked, after assigning the value to an M-Files field, whether the value also needs to be saved in an Intrexx data field.

5.4. Assign drop-down lists




M-Files fields for value lists have the data type Lookup or MultiSelectLookup (for lists with multiple selection) in M-Files. Each entry in a drop-down list in M-Files here has a unique ID (type integer), which is saved in the object. If an Intrexx data field or user-defined value is assigned to one of these M-Files fields, please note that the value in Intrexx can be used to determine the corresponding entry in the drop-down list in M-Files. If an Intrexx integer field is selected for the assignment, you must ensure that the M-Files drop-down list contains a corresponding entry with the same ID. Alternatively, the entry can be detected in the list using the displayed value.

Options
If a Lookup or MultiSelectLookup M-Files field is selected on the Data field mapping tab, clicking on the button, which can be found in the Options column, opens a dialog where you can define how the values from value lists in M-Files are determined. If a string field is assigned to the value list, for example, the value stored in it must correspond to the displayed value in the M-Files value list. This is case-sensitive. The strategy you choose here depends on the use case you want to achieve. If the IDs of the list entries are known in M-Files, the entry should be determined using the ID. If this is not the case, determining the entry using the displayed value can be used. Usually, the values are determined via the ID.

6. Properties - Authentication tab




Here, you can define which portal user should be used for authentication when accessing the M-Files vault. Further information about this can be found here.

7. M-Files data group handler

As soon as a file field for M-Files is added to an Intrexx data group and configured, the datahandler class in the expert attributes of the data group is changed to
de.uplanet.lucy.server.mfiles.connector.rtdata.RtDataGroupTableMFiles
This can also be entered later. The M-Files-specific data groups handler class is optional, but it provides additional functions in combination with Intrexx and M-Files. For example, the metadata values will be automatically synchronized from M-Files as soon as an M-Files data record is loaded on an Intrexx view or edit page. This ensures that an Intrexx portal user always sees the most current metadata in M-Files. In some cases, it can occur that metadata is changed in M-Files, but that the previous values are still stored in Intrexx.

8. M-Files in portal applications

8.1. Authentication

The first time a portal application is accessed that contains a data group containing M-Files metadata file fields, the user is asked to log in to the M-Files vault. This is only required once per session and M-Files vault. If Windows Integrated Authentication is defined, the user will be automatically authenticated upon first access. Also, a login is not required if a static user has been entered to the file field of the data group for M-Files authentication. After successful authentication, M-Files data can be accessed through the Intrexx application.

8.2. M-Files files in view tables

M-Files file fields can be placed in view tables so that files can be opened directly from tables. However, for performance reasons, files are not shown from M-Files in file fields by default if they are displayed in a view table. To enable this, activate the Show files from M-Files in view tables additionally option in the file field configuration. If documents should be downloaded directly from tables, this must be activated in the properties of the file field in the view table.



Please note that no thumbnails can be shown for M-Files files because these files are stored in M-Files, not on the Intrexx Portal Server. For this reason, no preview images can be generated by Intrexx.

8.3. M-Files files on view pages

M-Files files are displayed on view pages using the View file selection control.



Downloading files can also be enabled here.

8.4. M-Files files on edit pages

The File selection control on edit pages allows M-Files files and documents to be uploaded, edited, and saved in M-Files via Intrexx. All functions in standard Intrexx file fields are available for this.



In addition to enabling downloads, the upload process can be defined in the properties dialog on the Options tab. Fundamentally, new files are added to existing files in M-Files multiple file fields. However, it is also possible to replace files. You can also choose how many files can be saved per file field, as well as the maximum size of a file. In addition, there are advanced functions for uploading files, which affects the behavior of the control in the portal.



In the browser files can be dragged to the file control, which automatically uploads the file to the Intrexx server. When the edit page is saved, the uploaded files are transferred together with the metadata information to the M-Files server, and the new object ID and version is saved in Intrexx. Existing files can be deleted in M-Files via Delete.

This does not physically delete the file. Instead, a new version of the document object is created in M-Files that no longer contains the removed file. Objects of type "Single File" allow files to be updated or replaced by first removing an existing file and then uploading a new file.

8.5. M-Files files in drop-down lists

To make it as easy as possible for the portal user to update the M-Files metadata, it can be useful to create the same drop-down lists on edit pages in Intrexx as the value lists in M-Files, and to select either the ID or displayed value as the saved value. The determined value (ID or displayed value) must then be set accordingly for the metadata field. The IDs and display values for M-Files drop-down lists can be found via the M-Files Server Administration tool. To do so, open the desired vault and select the item for "Value Lists" underneath "Metadata Structure" ("Flat View"). All value lists are shown in the right-hand area. Right-click on a list and select "Contents" from the context menu to see the entries and their IDs for the drop-down list. The following example shows the display values and the ID for the "Classes" value list in M-Files.



In M-Files, the entries in drop-down lists are generated in most cases automatically through objects in relation to the list, for example if the Customer drop-down list lists all M-Files objects of the Customer type as entries. You can view these entries via "Metadata Structure" (hierarchical view).



It is also possible to populate drop-down lists from external systems via SQL queries. This is useful if the entries need to come from an Intrexx data group. This ensures an automatic synchronization between Intrexx and M-Files. You can find more information on this topic in the M-Files documentation. In Intrexx, a drop-down list can now be created on an edit page, the entries which reflect an M-Files value list. The values can also be defined from another application, from references, or user-defined. The following example shows how the M-Files Customer value list is recreated on an Intrexx edit page. In this case, the displayed values are used as storage values, meaning that the assigned metadata field in the data group must have the string type, and in the M-Files file field configuration, the display value must be used to determine the list entry.

9. Metadata updates

Since documents and files are only stored and maintained in the M-Files Vault, they always remain up-to-date when they are accessed through Intrexx. It is a little different, however, for document metadata. These are saved both in data fields of the Intrexx data group and in M-Files. This has the advantage of allowing metadata to also be searched in Intrexx and for data records to be accessed, without needing to access the M-Files server every time. The disadvantage of this approach is that the metadata for a document in M-Files may change with time, while the older values remain stored in Intrexx.

Since Intrexx is not automatically notified by M-Files when metadata is changed, metadata is updated in Intrexx as soon as a record is loaded on a view or edit page that contains an M-Files file field. When the page is saved, the updated metadata is saved in Intrexx again. If fields should also be updated in M-Files, then the Object ID must be incorporated as an edit field on edit pages.

Another approach that can be used to keep metadata synchronized between Intrexx and M-Files is via processes.

10. Searching in M-Files documents

Documents and files in M-Files data fields are only retained on the M-Files server. This means it is not possible for the Intrexx search engine to index the contents of the files, in order to make them available for search requests in Intrexx. Only the metadata that is saved in Intrexx data groups can be searched by the Intrexx search. The M-Files Web Service interface provides the ability to use the M-Files full text search for documents in M-Files. The results must then be prepared accordingly for Intrexx, so that when a search result is clicked, the document opens in the M-Files Web Access Client, or via a filter, the corresponding record in Intrexx is opened with the link to the M-Files document. To search the metadata saved in Intrexx for a document in M-Files, you can configure the Search in an application as usual. To do so, create a search configuration and select the metadata fields in the M-Files data group that you want to be indexed by the search engine. Afterwards, the search function in Intrexx can be used to search M-Files records for metadata. A further approach is to search using dynamic filters in Intrexx applications. This is done by defining filters on view tables that correspondingly filter data records according to the values in the metadata fields of the Intrexx data group. If you wish to allow searches for keywords in both the metadata and in the documents, the M-Files full text search can be used. M-Files documents managed in Intrexx can be searched and the results shown directly in Intrexx. It is also possible to search in the portal for documents in M-Files that were not uploaded through Intrexx. For the latter case, it is necessary for the portal users also to be given access to the M-Files Web Access Client in order to open located documents in it. The implementation of both approaches is described in the following.

10.2.1. Full text search of M-Files documents managed in Intrexx

In the following example, documents in M-Files are searched, and a corresponding record in an M-Files data group exists. First, create a view table to the M-Files data group for the search results. Additionally, an edit field is required for the search results.



Open the properties dialog of the view table and switch to the Dependencies tab.



There, click on "Add dependency" to define a new dependency. In the next dialog, click on "Add event" and select the Search button as the control and "onclick" as the event. Next, a filter is needed. Click on the Edit the filter in expert mode button in the Filter area of the dependency properties. Now copy the following XML fragment into the editor within the <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>
Then adjust the filter arguments according to your application:

10.2.2. Full text search of M-Files documents not managed in Intrexx

Via the M-Files REST Web Service interface, Groovy action handlers and Velocity templates can also be used to search for M-Files documents and to display the results in Intrexx. The instructions to call the search and display the results in this approach must be programmed individually, since they are always specific to the requirements. Please see the M-Files user manual for more information on how to use the M-Files REST API for the search.

10.3. Search using M-Files views

Corresponding to the full text search, it is also possible to search in M-Files based on existing views. To achieve this, proceed the same as for the full text search. The only difference is another filter handler is used for the search via views:
<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>
The meanings of the filter arguments are the same as for the full text search, with the exception of the "viewPathControlName" argument. Here, you can enter the name of an edit control that contains the path to the M-Files view to be used. However, you can also enter a fixed view path here, which causes the search to always be performed through the same view. The view path consists of the ID of the view in M-Files. For example, if you want to search with the "MyProposals" view in M-Files, first the ID of that view in M-Files must be determined. Open the properties of the view in the M-Files client to do so.



The ID of the view is located in the title of the properties dialog. To use this view in Intrexx, the view path would look like the following:

V110

If you want to search via a view hierarchy, you could use the following view path:

V110/V111

Alternatively, other view path expressions can be used as well. See the M-Files Web Service documentation for more information on this topic.

11. More information

Connector for M-Files
Consume M-Files data
M-Files in processes
Export / Import
Troubleshooting