This page contains our documentation of the CtrlDocs Controlled Co-Authoring application. Download as PDF (link inactive)

CtrlDocs Controlled Co-Authoring makes it possible to select documents in M-Files and check them out for Co-Authoring in OneDrive and Google Drive, with full access control in M-Files.

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

However, the native integration with OneDrive has some shortcomings, which we’ve addressed with this application.

Firstly, 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 required.

Both shortcomings have been addressed in our application by utilizing a service account.

In this 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.

Using a 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).

The application also supports Co-Authoring via Google Drive, using an equivalent configuration and underlying implementation, see

The application supports both a local M-Files installation, as well as M-Files Web.

Daily use

Checking out a document

The application currently supports the following files for Co-Authoring:

  • Text documents of the types .docx, .doc, .txt, .odt, .rtf
  • Powerpoint files (.pptx)
  • Spreadsheets (.xlsx)

To begin checking out a file to Co-Authoring follow the steps below.

  • Select a file of the before mentioned type.
  • Select 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 file.

Otherwise, 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.

Undo check-out

If the 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.

Figure 2: Undoing the check-out operation

Checking in a document

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 checked out.

Figure 3: Checking the document back into M-Files.

Context menu

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

Sharing documents

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 separate documents.

Figure 4

System administration

Configuration

Required objects and properties

A Person object: To share a document for co-authoring, a Person object representation is needed. We recommend using the free User Synchronization tool[1] 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.

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

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

Creating an Azure AD Application

For the 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 Registration”.

The name can be anything you’d like; the type should be “Web App/API” and the Sign-on URL should be https://login.live.com/oauth20_desktop.srf, as depicted in Figure 5.

Figure 5

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 Figure 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] .

Figure 6

Adding M-Files properties to the vault application

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

Figure 7

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” -> “Advanced”.

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 quotation marks).

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

Adding a Drive Configuration to the vault application

After installing the vault application in M-Files and applying the license, restart the server.

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

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

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

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:

https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?client_id=APPLICATIONID&response_type=code&scope=files.readwrite%20user.readbasic.all%20offline_access&redirect_uri=https://login.live.com/oauth20_desktop.srf

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

After 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:

https://login.live.com/oauth20_desktop.srf?code=AUTHORIZATIONCODE&session_state=

Grab only 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.

Preventing users from re-sharing a document in OneDrive

To prevent users who have been added to a document in OneDrive from re-sharing a Document to other people, a setting needs to be changed in OneDrive on the Service Account that runs the application. Information on how to disable re-sharing can be found here: https://www.uaex.edu/support-units/information-technology/O365/onedrive/onedrive_prevent_reshare.aspx

Metadata Card Configuration

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.

Installation 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”.

Figure 9

After importing the file, a configuration as depicted in Figure 10 should appear.

Figure 10

Error reporting

If the 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.

However, 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).

Localization

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.

Restrictions

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.


[1] More information on this add-on here: https://kb.cloudvault.m-files.com/Default.aspx?#3ECA226F-7B54-428B-B539-DE443E6134EC/object/415F7FB4-07F6-4329-9533-C4839388E262/latest


 [FSM1]Do we need to add instructions on adding permissions in the “Required permissions” section of setting up the app? If so, it probably needs Microsoft Graph -> User.ReadBasic.All

Close Menu