Connector for M-Files in applications

Create connection

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

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:

  • IntrexxGUID or ObjectID/ObjectVersion

    If the ID is generated in Intrexx (i.e. a GUID), which is saved both in the Intrexx data record and in its own field in the M-Files object, create a string data field for the Intrexx value. If the Object ID from M-Files should be saved in the Intrexx data record, create two integer data fields - one for the M-Files ObjectID and one for the M-Files ObjectVersion.

  • Title/Name

    For the object in M-Files, a title/name is required. Create a corresponding string data field in the data group to do this.

  • Class

    Objects in M-Files are always assigned to a specific class. An integer field is required. You can forego this data field if a static value is used for the class.

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.

Properties - General tab

Click here for more information about these settings.

Properties - Data field mapping tab

Mandatory fields

The following metadata is required to create or edit a document or object in M-Files:

  • Title/Name

    For the object in M-Files, a title/name is required.

  • Class

    Objects in M-Files are always assigned to a specific class.

Additional fields can be defined in M-Files as mandatory fields, depending on the document class in use.

Optional fields

These fields are optional but recommended.

  • Single file (boolean)

    Defines whether the document object may contain one (true) or multiple (false) files. Multiple files can be saved by default.

How to map fields and more information about this tab can be found here.

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.

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. And please note that 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.

Properties - Authentication tab

Here, you can define which portal user should be used for authentication when accessing the M-Files vault. Click here for more information.

M-Files data group handler

As soon as a data field for M-Files is added to an Intrexx data group and then configured, the data handler class in the expert attributes of the data group is automatically changed to:

de.uplanet.lucy.server.mfiles.connector.rtdata.RtDataGroupTableMFiles

. This can also be entered later. The M-Files-specific data group 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.

M-Files in portal applications

Authentication

When accessing a data group, which contains M-Files file data fields, with a portal application for the first time, the user will be requested to login to M-Files. 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.

M-Files files in view tables

M-Files file data fields can be placed in view tables to open files 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.

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.

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.

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.

Metadata updates

Seeing as documents and files are only saved and available in M-Files, they are constantly up-to-date, when they are accessed with 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.

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.

Intrexx search

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.

M-Files full text search

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.

Searching in M-Files data groups via Solr is only possible if the following requirements are met:

  1. The search configuration for the M-Files data groups may not contain M-Files data fields. This means that only metadata fields that are stored in an Intrexx data group can be indexed by Solr, and the M-Files full-text search is bypassed.

  2. In the "moduleConfig.xml" file in the portal directory "internal/search", the following property must be set to true for the M-Files <fileHandler>: adapterNeedsSolrIndex="true". This means that you can no longer use the M-Files full-text search (because Solr cannot index files in M-Files).

  3. At least Intrexx Version 9.2 with OU20 is installed.

After the changes have been made, the server must be restarted. In addition, the Solr collection and index need to be rebuilt for the M-Files search configuration.

Full text search of M-Files documents managed in Intrexx

In the following example documents are to be searched for in M-Files; these documents have a corresponding data set in a M-Files data group. 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.

Copy the following XML fragment between the <filter></filter> element in the editor.:

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>

Adjust the filter arguments according to your application:

  • In the first <arg> element, enter the data group's field GUID that contains the M-Files object IDs or the ID generated by Intrexx. The other entries refer to the attributes of the second <arg> element.

  • mfilesCfgGuid

    The GUID of the M-Files configuration to be used (can be found in the expert settings of the M-Files file field).

  • mfilesVaultGuid

    The GUID of the M-Files vault (can be found in the expert settings of the M-Files file field).

  • mfilesImpersonationGuid (optional)

    If the search request needs to occur using a static M-Files user, you can enter the Intrexx user GUID of this user here.

  • searchControlName

    Enter the name of the input control for the search expression here.

  • objectProperty

    This is used to inform the filter whether the results of the M-Files search should return the object IDs or the value of a freely chosen M-Files property type. For object IDs, enter ID. For property types, enter the ID of the M-Files property type. The decision of whether ID or property needs to be chosen as the return value depends on what you defined for Evaluation of the ID in the M-Files file field. If there is a field for the M-Files object ID in the data group, it is recommended to select ID. If an ID is generated by Intrexx and it is saved in an M-Files metadata field, enter the ID of the property type here (can be found via the M-Files administration tool).

  • returnType (optional)

    Specifies the return value of the function, either Integer or String. The default value is Integer.

  • defaultReturnValue (optional)

    Specifies the return value of the function if the search in M-Files does not return any results.

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

With M-Filesweb service interface it is possible to search for documents with Groovy action handlers and Velocity templates; the results can then be displayed 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.

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.

More information

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