Installing the Web API¶

Purpose¶

The Web API provides an alternative method of connecting M-Files with SQL Server. On-premise installations typically use an ODBC connection to allow a user to trigger context menu actions in M-Files for processing on the SQL Server. However, M-Files Cloud deployments—and other scenarios where the M-Files Server is not on the same network as SQL Server—can use secure HTTPS web service calls to trigger the same operations on the remote SQL Server.

The transaction calls from M-Files to SQL do not include any metadata. They instruct SQL to execute a stored procedure, which in turn uses standard M-Files connection protocols to exchange metadata between M-Files and SQL.

This guide applies to Release 5. Previous versions of the Web API must be replaced with the Web API that ships with Release 5.

This section describes the installation of the Web API. Refer to the section on installing and enabling the context menu prior to installing the Web API.

Whenever the Context Menu vault application is updated, the Web API must be updated as well.

Architecture¶

When a context menu call is made through the MFSQLConnectorVaultApp application, it checks whether the API URL in Configurations → Configuration → Web API Details is set. If it is set, it uses the URL to forward the call using an encrypted message string to the designated website. The website converts the call and passes it through the database connection string to the SQL Server and MFSQL Connector database. The calls supported using this method are restricted to pre-designed context menu actions, including:

Menu action to call a stored procedure or another web link.
Menu action for a specific object to pass through the context of the object and call a stored procedure.
Workflow action to pass through the context of the object and call a stored procedure.
Event handler action to pass through the context of the object and call a stored procedure.

Requirements: a web server with IIS 7 or later. The web server must have ODBC access to the SQL Server where MFSQL Connector is installed.

In summary, the installation steps are:

Install the website for the MFSQL Web API.
Configure M-Files (Configurations) for the Web API.
Set up or modify MFContextMenu if required.
Test using M-Files Desktop.

Website¶

The MFSQL Web API website for the web service calls from M-Files is provided as a ZIP file available in the installation folder in the 60_Addons subfolder. Note that each website is configured for a specific MFSQL Connector database; a separate instance must be installed in IIS for each vault to be connected to its MFSQL database.

Follow these steps to install or update the Web API using the ZIP file MFSQLConnectorWebAPI. Prior knowledge of installing a website and creating an application in IIS is assumed.

Run the installation on the web server.
Configure the website to use an SSL certificate.
Copy the ZIP file from the package installation folder for the correct version and database to the web server.
Extract the ZIP file to a temporary folder.
Install the site to your chosen location in IIS. For these steps we assume the Default Web Site and a folder named MFSQLConnectorWebAPI.
Stop IIS and copy the files from the temporary folder to MFSQLConnectorWebAPI. For a new installation, include the web.config file.
Before re-installing or updating, back up and delete the old website.
For updates, retaining the previous web.config preserves the website settings.
Ensure DNS and ports allow access to the website using a URL such as https://WebServer/MFSQLConnectorWebAPI.
Enable and configure the website as an application with an appropriate application pool. Use the default application pool if no other restrictions are required.
For first-time installation, set up the authentication and database connection for the Web API. See below for details.
Start IIS and test the application using the methods described below.

Enter the username and password for the authentication between M-Files and the Web API in the next step. The same username and password will also be entered into the M-Files Configuration.

Next, validate the connection from the web server. Use the MFSQL Connector database access credentials. The Connector installation creates a user with the required permissions by default. We recommend using the MFSQLConnect user. If the SQL password for this user changes, update it in the Web API as well.

Manual install¶

You may prefer to install the Web API manually on your web server. This may also be required when multiple vaults need to be connected to multiple MFSQL databases. The native installation files are included in the installation folder. By unchecking the IIS installation box during the package installation, IIS installation will be skipped so your web server technician can perform a manual installation.

The website files for manual installation are available in the installation folder.

Modify the following elements in web.config to allow the API to connect with a specific vault and database:

The connection string must point to the Connector database for the vault. Use the default username and password for accessing the Connector. If a different user or password is used, update this entry accordingly.

The API username and password must match the credentials used in the website.

The API URL setting is only visible to M-Files System Administrators. In the case of a cloud vault, M-Files Support will complete this.

Example: https://DNSName/MFSQLConnectWebAPI/

The connection string username and password should exist in the MFSQL Connector database. By default, the MFSQLConnect SQL Authentication user is created during installation. See Security for more detail.

The appSettings username and password encrypt the web connection between M-Files and the web server. Use the same values in the M-Files configuration.

Removing or reinstalling the packages¶

Before re-installing, delete the website MFSQLConnectWebAPI in IIS and the folder with the same name under the IIS root.

Configuration of M-Files¶

Use M-Files Admin and the Configurations tab to complete the installation in M-Files.

Complete the Web API details in the configuration tab of the MFSQL Connector Vault Application.

There is no need to complete any details in the connection string. Validate that the database connection in the website points to the MFSQL Connector database; the correct details should appear on the dashboard.

Right click Configurations in the Vault Setup and select Refresh after making changes to activate the new settings in the Configurator.

Testing¶

The best test to validate that the Web API is executing a call from M-Files to the Connector is to activate an action in the context menu.

Follow the Installing the Context Menu instructions to prepare an action to execute.

The table MFContextMenu shows the date and time when the action was received and executed from M-Files.

Error trapping¶

When the settings details are not shown, an error will be displayed in the Configurator error log. The most likely cause is an error in the connection string.