Controlled Co-Authoring Application is an alternative to the native M-Files
Co-Authoring tool, providing the same basic functionality of checking out
documents to Co-Authoring with OneDrive as well as Google Drive.
the native integration with OneDrive has some shortcomings, which we’ve addressed with this application.
the integration relies solely on OneDrive Personal, leaving out OneDrive for
Business. Secondly, whenever a document is to be checked out to Co-Authoring or
checked back in, logging into OneDrive through the M-Files user interface is
shortcomings have been addressed in our
application by utilizing a service
context, a service account is a OneDrive account that has been established for OneDrive for Business,
with the purpose of handling the organizations
files and permissions.
service account also allows for greater,
fine-grained control of permissions, meaning that, e.g. the policy for re-sharing files can be restricted to others
within the same organization or outright
banned. This is controlled through the options for the service account, through
OneDrive’s interface (see Configuration).
application also supports Co-Authoring via Google Drive, using an equivalent
configuration and underlying implementation, see
application supports both a local M-Files installation, as well as M-Files Web.
application is currently only compatible with the following files:
documents of the types .docx, .doc, .txt, .odt, .rtf
checking out a file to Co-Authoring follow the steps below.
a file of the beforementioned type.
the ‘Check out to Co-Authoring’ button from the sidebar.
Figure 1: Checking out a word document for Co-Authoring.
The system will respond by showing a dialogue window, informing of the consequences
of checking the document out; whenever a document is checked out to
Co-Authoring, it can no longer be edited by any other users through M-Files, as
this will cause a conflict. Responding
‘no’ to this prompt will stop the application from checking out the
the file will be uploaded to OneDrive, and a link to the file will be placed in the document properties in M-Files.
Note, that if the file has already been
checked out to Co-Authoring, the ‘Check Out to Co-Authoring’ button will no
longer be present in the sidebar. Instead it is replaced with the buttons ‘Undo
Check Out to Co-Authoring’ and ‘Check in from Co-Authoring’.
The only limitation of checking out files, is
the disk space available on the OneDrive service account.
document has been checked out by mistake, or, if the user wishes to revert the
document to its former state (before it was checked out), the check-out can be undone by selecting the ‘Undo Check Out to
Co-Authoring’ button in the sidebar. Note, that this button is only present
when a file has been checked out already.
When the Co-Authoring is
completed, and the document is to be
checked back into M-Files, the ‘Check In from Co-Authoring’ button can
be used. The document is then checked back into M-Files, with the changes from
OneDrive. Finally, the document is removed
from OneDrive. Note, that this button is only present when the document is
Figure 3: Checking the document back
The application also modifies the context menu for files of to
include the buttons previously mentioned, enabling the user to perform the
exact same actions by right-clicking on the file and selecting the desired
Sharing documents for co-authoring can be done both before
and after they have been checked out. This is done by adding or removing people
from the “Readers” or “Writers” properties on the Document, as depicted in Figure 4.
When hitting save, the new permissions are applied to the checked-out document. NOTE: Currently there is a
limitation when sharing to people external to the organization. No more than 30
external people on a given document can be handled at this time. There is no
known limitation as to how many internal people a document can be shared with
however. It is possible to share with more than 30 different external people on
A Person object: To share a
document for co-authoring, a Person object representation is needed. We
recommend using the free User Synchronization tool provided as part of the free Configuration Accelerator add-on in the M-Files
compliance kit to solve this. However,
any Person object can be used, if it has
an Email property of type text.
and Readers: Two
properties need to be created to select which users are to get Write or Read
access on a shared document on OneDrive. These should be of the type “Choose from list (multi-select)” using
Person object as the value source.
File ID: This
property is to save the ID of the newly checked out file on a Document. This should be a simple “text” property.
This property should have the alias “MF_PD_ExternalFileID” for the UI to work.
External File URL: This property is to save the URL of the newly
checked out file on a Document. This
should be a “multi-line text” property as these URL strings tend to be a little long.
Checked Out to Co-Authoring: This property is used to mark that a
Document has been checked out and then change the metadata card configuration. This should be of type “Select from list” using a newly created value-list called
“Booleans”, with value 1 being “True” and value 2 being “False”, and not a
Boolean property as these cannot be used
for metadata card configuration in the web.
vault application to work, an application needs to be created and registered on
your Azure Active Directory.
An application can be created by an administrator by navigating to https://portal.azure.com, then “Azure Active Directory”,
select your directory and lastly “App Registrations” and hit “New Application
You will need to retrieve an ID and a Password from
the application to set up Controlled Co-Authoring. The first ID is found on the first page of the newly created
application called “Application ID”. The Password needs to be created by going to the Settings page, by
clicking on the settings icon, and navigating to the menu point “Keys”. Under
“Passwords” enter a new “Key Description” and set it never to expire, as depicted in
6. After clicking Save, the newly
created password will appear. Save this
and the application ID to a text file as they are needed to set up the
Controlled Co-Authoring vault application[FSM1] .
installing the vault application in M-Files Admin, applying a valid license and
restarting the server, a new “Controlled Co-Authoring” menu will appear in “Configurations” -> “Other
Applications”. Inside the Configuration tab of this menu, you can expand the menu MFilesConfiguration.
PD_Collaborators should be set to the property that you
created for users that are to be given write access. Additionally, this
property must have the alias “MF_PD_Writers” (no quotation marks). This setting can be found by
right clicking the External File ID property -> “Properties” ->
PD_Viewers should be set to the property that you created
for users that are to be given read access only. This property must have the
alias “MF_PD_Readers” (no quotation marks).
PD_Email should be set to the Email property that is used on
the objects used in the Readers and Writers properties.
PD_DriveId should be set to the External File ID property.
This property must have the alias “MF_PD_ExternalFileID” (no quotation marks).
PD_FileUrl should be set to the External File URL property.
This property must have the alias “MF_PD_ExternalFileUrl” (no
And lastly PD_CheckedOutToCoAuthoring should be set to the
Checked Out to Co-Authoring property. This property must have the alias
“MF_PD_CheckedOut” (no quotation marks).
installing the vault application in M-Files and applying the license, restart
Then, a new
“Controlled Co-Authoring” menu will appear
in “Configurations” -> “Other Applications”. Inside the Configuration tab of
this menu, you can create a new Drive
type should be ONE_DRIVE, the client_id
should be the application ID you saved from the Azure AD Application, the
client_secret should be the password you saved from the Azure AD Application
and the redirect_uri should be https://login.live.com/oauth20_desktop.srf to match the Azure AD Application Setup.
Email Domains is to identify which emails are internal to your Azure/Office365
environment. If your email is [email protected], simply enter corporation.com into
the configuration field. Now your configuration should look something like Figure 8.
For the authorization code, you will need to log in as the user that will be responsible for uploading and sharing documents (the
service account) via a specific link:
replace the APPLICATIONID part with your application ID from the Azure AD
Application and access it through a browser. For this step, you must log in using the account that is being used for managing uploads and sharing,
not your personal account.
logging in and allowing the application access to the account, it will leave you with a blank page. Find the URL
of the current blank page and extract the “code” part of it. Be sure to not include the very end part of the URL.
The format is this:
the Authorization Code part of the URL, between “code=” and
“&session_state” and paste it into the configuration of the vault
application and save the configuration. The authorization
code is only valid for 5 minutes and is used only for the first-time setup. In case the password for the
account is changed, or something else
happens, a new authorization code should be obtained and saved into the configuration
the same way.
To enable a
richer and easier user experience in the M-Files client and web, there is a
provided metadata card configuration that you can use to get going. This
includes a section for co-authoring properties as well as changes to the
metadata card to make it clear that something has been checked out.
of the provided “mfiles.metadatacard.Configuration.json” file is done inside of
the “Configurations” -> “Metadata Card” menu in the M-Files Admin. Right
click on “Configurations”, as depicted in Figure
9, and select “Import from File…”,
select the file and hit “Open”.
application encounters an error during initialization, it is reported directly
to the M-Files server’s event log, providing a short message and a stack trace,
that can be used to diagnose the error.
once the application has been initialized, the preferred error logging
procedure is to provide a system administrator with an email, detailing the
same information. To set the system
administrator email(s), the application configuration contains a field named
“Admin Emails”. This field must contain one or more emails (in the
case of several emails, make sure that each email is on a separate line).
Currently, user interface of the application is localized
for American English (en-US) and Danish (da-DK). However, the user interface is
built so that it can be localized to any of the languages that M-Files support.
System information and errors, however, are always reported
in American English.
Google Drive Integration
The application also supports Co-Authoring using Google’s
Google Drive API, with very little difference in the way the user interacts
with the interface and the configuration of the application.
Figure 11: Google Drive Integration
Unfortunately, the integration has some restrictions due to
the difference in vendors.
The Google Drive API imposes several limits on the
integration, particularly concerning file sizes. This is primarily due to the
file type conversions that must take place to allow Co-Authoring of any
non-Google documents using Google Drive (or rather, using Google Docs, which is
what Google Drive relies on for Co-Authoring). At the time of writing, the file
size limit for uploads to Co-Authoring using Google Drive is 8 megabytes. This
limit is enforced within the application and will manifest in an error if a
larger file is checked out to Google Drive Co-Authoring.
Furthermore, Co-Authoring with using the Google Drive
integration may impose limits on document formatting or content. Upon
converting a file, Google Drive may cause loss of information, usually the
effects are limited to formatting. In the case of unacceptable information loss
upon checking in a document into the Google Drive integration, it is
recommended to use the ‘Undo check out’ functionality, as it will revert the
document to its older state.