Information on this page is only applicable to M-Files (server) version 12.0.6400.37 and higher.

Intelligent Metadata Layer

The M-Files Intelligent Metadata Layer is an industry-leading concept, available for M-Files 2018 upwards, that allows businesses to intelligently manage information regardless of in which ECM system or silo it originates.

The Intelligent Metadata Layer currently consists of two sets of functionality:

Intelligence Services provide functionality to suggest metadata property values for documents in M-Files, aiding the speed and accuracy with which objects can be added to M-Files with the correct metadata. Partners can build their own intelligence services to provide custom intelligence functionality, either for their customers or to sell via our Certified Application Partner program.
External Repository Connectors allow businesses to expose information held in other systems (such as network file shares) into M-Files. Information can be optionally “promoted” by providing it with metadata information, at which point the object can take part in M-Files functionality such as workflows, views, notifications and the like. The file information continues to reside in the remote system. Partners can build their own external repository connectors to integrate into other repositories, either for their customers or to sell via our Certified Application Partner program.

Using Intelligent Metadata Layer functionality via the REST API

Intelligence Services

Intelligence Services can be invoked - and their suggestions collated - by executing a POST request to /REST/objects/automaticmetadata. The HTTP request body should contain a JSON-serialized AutomaticMetadataRequestInfo object, and the response body will contain an array of JSON-serialized PropertyValueSuggestions.

Metadata suggestions can be provided in the following scenarios:

For existing objects in M-Files
- Ensure that AutomaticMetadataRequestInfo.ObjVer contains information about the object version to query.
- Ensure that AutomaticMetadataRequestInfo.ObjectType is populated with the object type you wish to create (e.g. 0 for documents).
For one or more files that have been uploaded, but where the object has not yet been created
- Ensure that AutomaticMetadataRequestInfo.UploadIds contains the ids returned from a call to /REST/files.
- Ensure that AutomaticMetadataRequestInfo.ObjectType is populated with the object type you wish to create (e.g. 0 for documents).

External Repository Connectors

External views and unmanaged content are not returned, by default, by the M-Files REST API. This is to aid legacy compatibility, as these new types of content require additional logic to process and handle.

Enabling External Repository Connector functionality

To ensure that external views and unmanaged content are returned, the X-Extensions header must be provided during the call to retrieve an authentication token. The X-Extensions header must have a value of IML.

If this header is not included on the call to retrieve an authentication token then external content will not be returned by the REST API.

External view folders content type

Once IML functionality is enabled, querying for view contents may start to return external view folders, and searches may return unmanaged objects. This is most often seen when querying the root/home of the vault, as any external repository connections are listed here.

Navigating external view folders

After enabling external repository connector functionality, retrieving items from the vault root (a GET request to /REST/views/items) will return external view folders for any configured vault external repository connections, in the same way that the M-Files Desktop Client does.

To retrieve items from within an external view folder, a request must be made to /REST/views/(path)/items including the external view folder path encoded as shown on the encoding syntax page.

For example, for an external view folder in a repository with ExternalRepositoryName of myrepository and an external view ID of 1234, the request would be of the format:

http://myfiles.mycompany.com/REST/views/umyrepository%3A1234/items

If the above view folder had a sub-folder with ID 5678 then the request would be of the format:

http://myfiles.mycompany.com/REST/views/umyrepository%3A1234/umyrepository%3A5678/items

If the external repository connection uses personal authentication then the above endpoint(s) may return a 403 HTTP status. This happens when the user has not already authenticated to the repository, or if their authentication is no longer valid. The user must log into the repository before this connection can be used.

External object repository object versions

Once IML functionality is enabled, querying for view contents or performing searches may return external objects. External objects can be identified as their ObjVer will contain populated ExternalRepositoryName, ExternalRepositoryObjectID and ExternalRepositoryObjectVersionID properties.

Note that objects from external repositories may be unmanaged or managed. Unmanaged objects have not been promoted, do not have an internal M-Files ID (ObjID.ID) assigned, and will not contain extended metadata. Managed objects have been promoted are assigned an internal M-Files ID (alongside external repository information), and will contain other metadata such as the object’s class.

Retrieving properties of objects from external repositories

The object version properties endpoint supports both managed and unmanaged objects.

For an unmanaged document with an ExternalRepositoryName of myrepository, an ExternalRepositoryObjectID of 123456 and ExternalRepositoryObjectVersionID of version1, the request would be of the format:

http://myfiles.mycompany.com/REST/objects/0/umyrepository%3A123456/uversion1/properties

Note that for unmanaged objects the amount of metadata returned will be limited.

Promoting unmanaged objects

To promote an object (to convert it from an unmanaged to a managed object), execute a PUT request to the setting properties on multiple objects endpoint.

The properties for the new object must include, at a minimum, the object class (built-in property definition with ID 100), and all mandatory properties for that class.

Demoting managed objects

If an object has previously been promoted from an external system and is no longer required to be managed by M-Files (e.g. it was promoted by mistake) then the metadata held against that object can be removed by demoting the objects.

Object operations supporting external objects

The following endpoints can be used to retrieve information for unmanaged objects (i.e. objects residing in external systems which have not yet been promoted).

When dealing with umanaged objects, M-Files attempts to perform the requested function directly against the external repository. Depending upon the repository, and support of the connector, these functions may fail.