Connector for M-Files

General
Setting up the data source
Application development
M-Files in portal applications
M-Files in Intrexx processes
Import and export of M-Files configurations
Troubleshooting

General

The Connector for M-Files enables the M-Files document management system, named M-Files DMS in the following, to be used as a storage method for files that are stored in Intrexx data groups as usual on the local file system. In addition to saving files, metadata for a file in M-Files can be maintained and edited in Intrexx. For the portal users, therefore, it makes no difference whether a file available in the portal is stored locally or in the M-Files DMS. The following chart shows the role of the adapter and the involved components.



A file field in an Intrexx data group here corresponds to a Document object type and a class in the M-Files DMS. One or more files can be stored for each file field, depending on whether the document in M-Files corresponds to a one-file or multiple-file document type.

Files cannot only be saved to the M-Files DMS, but can also be directly opened and/or downloaded from M-Files in an Intrexx portal. Access to M-Files here occurs via a specific M-Files user, through which all permissions in M-Files are taken into account. Depending on the authentication mode, Intrexx portal users can log on directly to M-Files, or access can occur through a static user that is saved to the file field configuration.

Fundamentally, Intrexx will be considered as the leading system when discussing it in combination with M-Files. This means that files are uploaded and metadata is entered to Intrexx, and then they are passed to M-Files. This also means that metadata is saved both in M-Files and to Intrexx data group fields, though files are only saved to the M-Files DMS.

A full text search of the document contents is not possible in Intrexx without additional steps, since the files are kept in M-Files. In this case, it is recommended to use the M-Files Web Access client to search.

The same actions are available in the Intrexx Process Designer as those that are available for normal Intrexx data groups. This allows files to be transferred from Intrexx to M-Files and back again controlled by processes.

Setting up the data source




A new data source can be created from the context menu.



Information about the context menu functions can be found here.

Application development

Data groups

To enable saving metadata and documents in M-Files through Intrexx, an Intrexx data group is required. External data groups are currently unsupported by the adapter. The fields of the data group can then be linked to M-Files metadata fields. For files, a file field is added to the data group that receives a special file handler class for M-Files.

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

In the first step, the fields for the metadata are created, which will later be linked with M-Files.



Create a data group for the M-Files connection or select an existing one in your application. Add all required data fields to the data group that need to be linked to fields in M-Files. First you must decide how a data record in Intrexx will be connected with a document object in M-Files. To do this, you can either generate a value (such as a GUID) as a common ID for Intrexx and M-Files, which will be saved in its own field, both in the Intrexx record and in the M-Files object. Alternatively, you can save the object ID from M-Files to the Intrexx record.

At least the following fields are required in the data group:

File fields

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.



To do so, add a new field of type File to the data group and click on more...:



In the dialog, select the option of Other handler under Primary key data type. In the drop-down list, select the entry for de.uplanet.lucy.server.mfiles.connector.MFilesFileHandler and confirm with OK.



Click on Edit data field to open the properties for the new file field.



The Title of the field and the previously selected handler class are shown on the General tab. Specific information is additionally required: The last option to also Show files from M-Files in view tables additionally controls whether the contents of M-Files file fields are will also be shown in view tables.

This can be useful for end users if documents need to be opened directly from tables. However, please note in this case that the option will require a large amount of processing power, since each record in the table needs to be found as a document in M-Files. For this reason, it is recommended to only show documents on view pages for a data record.

Metadata field assignment


M-Files mandatory fields

In order to enable a document (object) to be successfully created or edited in M-Files, M-Files defines several metadata fields that are mandatory, as well as fields that are optional but recommended. In the following, the mandatory and optional fields are described that should be maintained in Intrexx - through field assignments or by user-specific values.

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

Optional fields

Assigning Intrexx fields

In this step, the Field assignment tab is used to assign Intrexx data fields and values to M-Files metadata fields.



The M-Files metadata fields of the previously selected vault are listed on the left-hand side of the dialog. The right-hand side shows the fields of the Intrexx data group, as well as the fields of a parent data group and user-specific values as applicable. Furthermore, the M-Files fields can be filtered by class to provide a better overview. Mandatory fields in M-Files are designated as such with this symbol.

Use the arrow keys to assign a field in M-Files to an Intrexx field. This means that when a record is saved in Intrexx, the value from the Intrexx field is automatically saved to the linked M-Files field in M-Files. Please note here that the field data type in M-Files needs to be compatible with its counterpart in Intrexx.

Assignment of user-specific values

In addition to data fields, M-Files fields can also be assigned to user-specific values. Click on Add value.



Select a static value, system value, GUID or null value here. This can be helpful, for example, if the same value always needs to be used for the mandatory M-Files field Class. Thus, a static value of 10 can be created here and assigned to the class. 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. Calculated values are not saved by default to Intrexx data fields, but are rather saved in M-Files fields. 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 requested after assigning the value to an M-Files field whether the value also needs to be saved in an Intrexx data field.



The setting Save value in the data field can be activated here. Click on OK.



The setting Save value in data field can be edited by clicking Save value in data field in the Field assignment tab dialog. Click on Add value.



If you select the option Static value here, the settings can be defined by clicking Edit static value.



Select the desired Data type (character string, number, Boolean (logical value), date/time). In the Value area, the fixed value will be entered, whereby with a date/time data type you have the ability to dynamically adjust the date. For the data type Character string, by clicking on Add GUID a unique ID can be created that will be directly entered to the Character string field. In Time zone, select the desired time zone. Click on OK.



If you select the option System value here the settings can be defined by clicking Edit system value.



Select the desired system value Type here. For the User value type, fields can be selected from the User Manager. For the Request value, Session value, and Processing context types, the name of the variable will be entered to the Value field. In the lower area of the dialog the system value that will be entered when no value is set can be defined.

Assigning drop-down lists

Just like in Intrexx, M-Files provides the ability to define drop-down lists for data fields. Fields with drop-down 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 stored to the object.



Drop-down lists in M-Files are able to be assigned values from Intrexx data fields or static values. Please note here that the value in Intrexx can be used to determine the corresponding entry in the drop-down list in M-Files. If an Intrexx field of type Integer is selected for the assignment, you must ensure that the M-Files drop-down list contains a corresponding entry with the same ID value. Alternatively, the entry can be detected in the list using the displayed value. If a string field is assigned to the list field, for example, the value stored in it must correspond to the displayed value in the M-Files drop-down list. Please make sure that the letter case is correct here. The strategy you choose here depends on the application case you want to achieve. If the IDs of the list entries are known in M-Files, the entry should be determined based on the ID. If this is not the case, determining the entry based on the displayed value can be used. The corresponding dialog for this is opened via Options behind an M-Files Lookup/MultiSelectLookup field. By default, the values are determined via the ID.

Authentication

In the last step of the file field configuration, you can use the Authentication tab to define which portal user should be used for authentication when accessing the M-Files vault.



The currently logged-on portal user is used by default here. If no M-Files session exists for this user and User name/Password was chosen as the authentication method in the configuration, the user is requested, in the portal, to log in to M-Files. There are cases in which access to M-Files should always occur through the same M-Files user, regardless of which portal user is currently logged on. This is the case, for example, if an M-Files user does not exist for every Intrexx user, or documents from Intrexx should always be saved under the same user in M-Files. A static user can be chosen in this dialog for this purpose. This is an Intrexx user who was assigned an M-Files user account in the M-Files configuration. However, a static user can also be created directly in the dialog. As soon as a user of this type has been saved in the file field, all access to M-Files through the data group occurs with this M-Files user account. This means that interactive authentication to M-Files will no longer be necessary in the portal. This also allows simple single sign-on scenarios to be realized, without needing to set up Kerberos authentication.

M-Files data groups 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 are 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.

M-Files in portal applications

Authentication

The first time a portal application is accessed that contains a data group containing M-Files metadata file fields, the user is requested to log on to the M-Files vault. This is only required once per session and M-Files vault. If Windows Integrated Authentication is active, the user will be automatically authenticated upon first access. Also, no logon is 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. With M-Files data groups, the same functions are available in this way to the portal user as with normal Intrexx data groups. In regard to file operations, there are only a few special characteristics to note.

File operations in view tables

M-Files file fields can be placed in view tables. In this way, files can be opened directly from tables. However, for performance reasons, no files are shown from M-Files in file fields by default if they are displayed in a view table. To enable this, the Show files from M-Files in view tables additionally option in the file field configuration. If documents need to be downloaded directly from tables, this must be activated in the options for 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.

File operations on view pages

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



A download for the files can also be enabled here.

File operations 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 through Intrexx. All functions in standard Intrexx file fields are available for this.



In addition to enabling downloads, the upload process can be defined. 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 expanded functions to upload 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.

File operations in drop-down lists

To make it as easy as possible for the portal user to maintain the M-Files metadata, it can be useful to create the same drop-down lists on edit pages in Intrexx as the drop-down lists in M-Files, and to select either the ID or displayed value as the stored 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 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 fill drop-down lists from external systems through 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 in which reflect an M-Files value list. The values can also be defined from another application, from references, or user-specifically. 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

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 changes, 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 - Available search options

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.

Searching in M-Files documents - 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.

Searching in M-Files documents - 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 documents - M-Files full text search - 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.



In the next step, open the Dependencies tab in the view table properties. There click on Add dependency to define a new dependency. First, a trigger event is required. To enter it, click on Add event and select the edit field as the control and, for example, onclick as the event.



Next, a filter is needed. To do so, click on the Edit the filter in expert mode button in the Filter area. 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: Now confirm the dialog with OK and publish the application. The search is now available in the portal for use.

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

Through 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.

earching in M-Files documents - 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.

M-Files in Intrexx processes

User switch action

Since no interactive user authentication to third-party systems is possible in processes, a logon to M-Files must occur before M-Files actions can be initiated. Two different options are available to achieve this. The first is to enter an additional user to the M-Files configuration that can be selected for authentication. For timer-controlled data group processes, the user can be directly selected in the timer configuration.



Another possibility is the user switch action. This makes it possible to switch to the M-Files user from within a process.



To do so, create a new user switch action and select M-Files as the action type. In the next step, the user can be selected that will be used to run the subsequent actions.

Metadata synchronization

In contrast to files, the metadata of a document saved to M-Files via Intrexx is saved to the Intrexx data group fields. If metadata for a document is changed directly in M-Files, it cannot be automatically synchronized in Intrexx without performing some additional steps. For this reason, Intrexx automatically refreshes the metadata for an M-Files object as soon as the record is opened on a view or edit page. To save the current metadata in Intrexx as well, the user must then click on the Save button. This procedure can also be automated with an Intrexx process, which enables the metadata for an Intrexx data group to be synchronized with the objects in M-Files in regular intervals. To do so, create a new process and create a new timer event.



In the timer configuration dialog, select the M-Files data group and define a filter if needed. Next, select a user that will have its logon data saved to the M-Files configuration.



Now add a new data group action to the timer event handler and select Update record. Select the same data group as in the timer for the target data group, then select both ID fields as the Simple filter. In the next step, Field assignment, you can now assign the fields from the source data group to the target data group, for which the M-Files metadata will be read again and saved. When doing this, please note that the file fields cannot be synchronized here, since otherwise a new version would be created in M-Files. After closing the dialog, the process can be saved and run. By reading the records from the source data group, the metadata is read again from M-Files, then saved to the assigned data fields in Intrexx again.

File transfer between Intrexx and M-Files

Usually, files and documents are only saved physically to the M-Files server, then loaded by Intrexx at runtime when a user accesses an M-Files file in the portal. In some cases, it can also be useful to transfer files from M-Files to Intrexx or to copy existing files from Intrexx portals to M-Files. Additionally, in the data group actions, file fields can be assigned between Intrexx and M-Files data groups. If an M-Files data group is read from and written to an Intrexx data group, the files are copied from M-Files to the Intrexx portal server. In reverse, files can be copied from Intrexx applications to M-Files by reading from an Intrexx data group and writing to an M-Files data group. By using filters on the source data group, you can define which records (and therefore files) should be transferred to the corresponding target system. The following example makes clear how to transfer files from Intrexx to M-Files:



First, the records are read from an Intrexx data group timer-controlled. Next, a user switch action is used to log on to the M-Files server. Afterwards, the files and metadata are transferred from the Intrexx data group fields to M-Files using an M-Files data group action. The field assignment looks like the following to do so:

Import and export of M-Files configurations

All information regarding this topic can be found here.

Troubleshooting

Request tracing

For error analysis, the M-Files requests and replies can be logged in the Portal Log file. Activate tracing as follows:
  1. Open the log4j.properties file from the /internal/cfg directory in a text editor.
  2. Navigate to the logging for M-Files section and change the value from INFO to DEBUG: 
    # logging for M-Files
log4j.logger.de.uplanet.lucy.server.mfiles.connector=INFO, File
  3. Restart the portal service afterwards.
  4. For each M-Files action, the request details will now be logged in the portal.log file.
Example for a request/response tracing entry: 
DEBUG MFilesHttpRequest[WebConnectorWorker-localhost:8102-3]
M-Files request: http://mfiles/REST/objects/0/112/latest
DEBUG MFilesHttpRequest[WebConnectorWorker-localhost:8102-3]
M-Files response: {"Title":"Test1","EscapedTitleWithID":"Test1(ID 112)","DisplayID":"112","ObjVer":{"Version":4,"ID":112,"Type":0}

SSL connections

For SSL connections between the Intrexx portal server and an M-Files service, the Certificate Authority that provided the service certificate must be added to the certificate store of the Intrexx portal server. Self-signed certificates are an exception to this, which are not provided by a recognized Certificate Authority. In order to enable SSL connections to services with self-signed certificates, the check on the "certificate chain" must be deactivated. This is possible at the service level via a system property. To do so, open the <INTREXX_HOME>/org/<PORTAL_NAME>/internal/cfg/portal.cfg file in a text editor and add a new <systemProperty> entry to the <environment> section: 
<systemProperty name = " de.uplanet.lucy.server.mfiles.connector.ignoreServerCertificates" value="true"/>
After saving the portal.cfg file, the Intrexx portal server must be restarted for the changes to take effect.