Overview
This article lists some common questions and issues with the M-Files Web Companion. You can read more about it in the User Guide page.
Web Companion does not seem to work after installing it - basic checklist
Make sure it is running - you should see an icon in the OS tray after the installation is completed.
If you do not see the icon after waiting for a bit, or after you know you have installed or used the companion, re-launch M-Files Web Companion. On Windows there should be a shortcut for it on the Desktop, or you can search in Start; on Mac it is in the Application folder.
Make sure that local network access is allowed, for more details see: M-Files Web: wants to look for and connect to any device on your local network. Note the "Details about the M-Files Add-Ins" section as there is special handling needed here due to the browser behavior.
Make sure you have refreshed the web client after the companion installation.
After the vault access registration, you must redo the action in the web client (e.g., double click and checkout the file again).
If you have not performed the vault access registration, you will get the same prompt the next time you do an action through the Web Companion (opening in a desktop app) and the Web Companion will not work until the vault is marked as trusted via that access dialog.
Checkin does not save the content
Make sure that the changes are saved in the desktop app, and that the app is closed.
Some files do not open
- Make sure the file type is supported. The supported file types listed in this article: Installing M-Files Web Companion.
- Make sure the file is under 200MB.
When to force quit the Web Companion in Mac?
Before a shutdown, restart, uninstall, update or logout of the Web Companion in Mac, you must force quit the Web Companion app (Apple Menu at the top left corner -> Force quit -> Quit M-Files Web Companion).
Firewall
M-Files Web Companion communicates with the web client in the browser on a few ports that you must allow through the firewall. Generally, you should be prompted when you install it. These are ports opened on the localhost (127.0.0.1) and Web Companion will listen on them.
Here is the list of ports: 48951 is the default port, if it is in use by some other app, the following will be tried: 48952, 48953, 62522, 62523, and 62524.
M-Files Web Companion communicates directly with the M-Files Server, but it uses the web client address and port that it receives from the browser. The process initiating this communication is the M-Files Web Companion process. In practice, it acts like the web client in terms of the network requests it makes.
When you check-in a file in the web client, the updated content will be sent by the Web Companion app to the M-Files Server.
Note that Web Companion does not use the system proxy that the machine may have set up and so may be subject to different routing and/or firewall rules than other applications.
Self-Signed Certificates
The Web Companion communicates with the M-Files Web Endpoint which is usually an IIS server. It is customary to have a TLS certificate on that server to allow for encrypted HTTPS communication between the endpoints.
Self-signed certificates are not supported.
Using them will cause errors in communication and Web Companion will not function. This will usually manifest with the file you double clicked not opening as you would expect. You would see errors in the browser dev tools (network tab) that point to a certificate being invalid in such a case. The errors could be similar to "UNABLE_TO_VERIFY_LEAF_SIGNATURE" or "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", or other similar errors mentioning certificate issues.
Typically, opening the same site with a browser will prompt you that the certificate is not trusted or not valid, but keep in mind that while the certificate may be added to the browser certificate store and so trusted even if it is a self-signed one, this is not possible for the Web Companion. Implementation for such certificates on Windows is logged with ID CE-958.
Note that Web Companion does not use the Windows Certificate Store, so even if you add a custom self-signed certificate as a Trusted RCA, this will not let it work for Web Companion, even though it will work for browsers and M-Files Client.
Does the Web Companion work in the add-ins?
The M-Files Web Companion works with the web client, so it also works with the add-ins (Salesforce, Teams, Sharepoint Online).
It does not work with the Classic Web client. For that, you can use the M-Files Chrome Extension that serves a similar purpose.
Are there logs?
Logs from its operation are saved in the following path:
Windows: Users Directory\<username>\.MFWebCompTemp\MFiles.log
MAC: Users Directory\<username>\.MFWebCompTemp\Mfiles.log
Also collect the browser logs (network and console tabs), see this article: M-Files Web Companion: Troubleshooting FAQ
When are temporary files deleted?
When the check-in operation is performed, the web companion tries to delete the file. This is one reason why you should close the app before checking in.
Web Companion will try to delete unused files at 2AM every day, and when the machine restarts.
Temporary files are stored on the client machine in the following path:
<user directory>\.MFWidgetTemp\<vault identifier>\
Where the vault identifier is comprised of the protocol and domain name. The files for each vault are stored under that folder.
What does double-click do and why did it change after installing Web Companion?
The default action when you double click a document has the following set of priorities:
If the web companion is installed:
- The default action is to try to open the file in the native desktop application.
If the web companion is not installed, there are two options:
- If Office Online editing is enabled in the vault and the document supports it, it is opened in Office Online.
- If Office Online editing is not enabled in the vault, the file is downloaded.
If you use the context menu, the web companion provides you with a separate option called "Open in Desktop app" that does not interfere with previous functionality.
Why do I have to login again to the Web Companion, I already logged in in the web client?
At the moment, the Web Companion does require that you login to the vault with your current method (e.g., via Azure AD, Okta or other OAuth identity provider, or your M-Files login credentials) before it can operate for the first time, and also if it has not been used for 35 days.
A future release may allow SSO to work and avoid a second login, but at the moment this is necessary, and it is also considered a security feature.
OAuth Setup Requirements
There are three things to keep in mind with the Web Companion app when using OAuth:
- It relies on the "webuiintegrator.html" RedirectURI that the M-Files Add-Ins use so you must have it whitelisted in your IDP.
- If Web client is your default web client: https://vault-dns-name/webuiintegrator.html
- If the Classic Web client is your default web client: https://vault-dns-name/vnext/webuiintegrator.html
- It uses an embedded browser that various security policies may block (it is not a full Chrome, Edge or WebView) so you may need to whitelist it.
- It uses the default login mechanism that you see in the Web client landing page. For example, if you have set up the Default Configuration for OAuth, you will not have the option to enter M-Files Login credentials, and you will only see the federated authentication flow.
- Web Companion does not store tokens explicitly (refresh tokens, access tokens or id tokens). Tokens used in the OAuth flow are stored in the session storage and the browser clears them when it is closed.
- Web Companion requires OAuth authentication only on the initial registration (or after 35 days of inactivity, see "Why do I have to login again to the Web Companion, I already logged in in the web client?").
- Once the initial authentication is completed, Web Companion does not use OAuth anymore. The Web client logs the user and it registers the Web Companion tasks with M-Files Server when you perform an action in the Web client that requires Web Companion. Then, Web Companion works with the server with its own authentication that was generated and stored during the initial authentication, it does not use the user session.
Does Web Companion support Anonymous Authentication?
Yes, if you have enabled Anonymous Authentication in your vault, you can access it without logging in to the web client, and you can also use the Web Companion. You still have to approve the server access prompt, however. The checkout and edit actions will not be available, so double clicking an item will open it in read-only mode. If you do edit the file somehow (e.g., your app allows you to modify read-only files), you will be unable to check-in the changes.
How do I uninstall the Web Companion?
Windows: Go to Control Panel -> Programs -> Programs and Features -> find and select the M-Files Web Companion and click Uninstall.
Mac: First, force quit M-Files Web Companion, then go to Applications -> find and select M-Files Web Companion and move it to Bin.
What is the MacOS certificate?
MacOS requires HTTS communication for internal servers, and so a self-signed certificate is generated for the server Web Companion uses to communicate with the web client in the browser.
This certificate is generated during the installation and must be renewed every 1 year. Its expiration time cannot be controlled.
The user will get prompts to renew it as they use the Web Companion, and the expiration time starts drawing near.
If you do not create or renew the certificate in time, or it goes missing for another reason, the Web Companion will be unable to communicate with the web client, and so it will not function.
Launching the Web Companion app manually (make sure it has been exited before that) will prompt you for the certificate generation so it can work again (reload the web client after recreating the certificate).
You should not need elevated privileges to generate a certificate, use your own user credentials when prompted.
If the certificate is not valid for some reason (expired and not renewed, or you did not enter credentials in the prompt so the operation can complete), you will get prompted to install the Web Companion again after trying to open a document from it. See more here: Web Companion app does not work in MacOS due to invalid certificate.
Why does the application window open in the background or minimized?
If this happens to you, look for it in the taskbar or tray, and activate it. We hope to be able to improve this behavior in a future release so that the desktop app opens always in the foreground.
MacOS and GPO distribution – name change may be needed
If you are distributing the M-Files Web Companion via GPO on Mac machines, and you face an issue with the default dmg package name, you may need to replace the whitespace with dashes in the package name. That is, from “M-Files Web Companion” to “M-Files-Web-Companion”.
You can find an example of GPO policy to distribute it here: Distributed Installation of M-Files Web Companion.pdf
Language Translations
At the moment, M-Files Web Companion is only available in English. After installation, there isn’t much interaction with it for the end user, however, so this should not prevent its use – you still use M-Files Web interface (which has translations) and your desktop program for editing documents.
Is it possible to hide the "Install M-Files Web Companion" option from the M-Files Web menu or the "Open in desktop app" option from the context menu?
Not at the moment. We have recorded an improvement request with ID 169459 to add such a configuration option for administrators. You can follow the improvement's availability with this ID from our Release Notes.
Multi-User Environments (VDI) are Not Supported
Web Companion does not support desktop virtualization environments (such as Citrix, AVD, MS RDS). An enhancement to add such support is in our backlog with ID CE-167.
Important: You must NOT use M-Files Web Companion in such a desktop virtualization environment or multi-user setup. If you do, there is a risk of data leaking between users (e.g., a file opened by one user to be opened for another).
