Document configurations

A CtrlSync vault can hold several kinds of connection — a Teams channel, a SharePoint document library, a project site — and each kind needs its documents handled differently. A document configuration, listed under Connection Configurations, decides that for every connection of one class: which M-Files class, workflow and permissions a synchronised document gets, which properties it inherits from its connection, and what happens when something fails.

Connection Source Class is the class of connection object the configuration applies to. Every document that arrives through a connection of that class is handled by this configuration.

Give each document configuration its own Connection Source Class. Two configurations naming the same class both run against the same connections on the synchronisation schedule, while the check-out, deletion and upload handling uses only the first of them, so one connection ends up handled two ways.

Every setting in a document configuration, with its data type and default, is listed under Connection configuration. This page covers the settings that interact.

Classes, workflow and permissions

Default Document Class is the class a document gets when no property mapper sets one. The Class white-list and Class black-list decide which documents CtrlSync handles at all. A new file whose class, from a mapper or the default, is not allowed is not imported. A document already in the vault whose class is not allowed is no longer updated from the source, and CtrlSync sends none of its changes, check-outs or deletions to the source. With a white-list, files that end up with the default class come in only if the default class is on the list.

Default Workflow and Default Named Access Control List are applied to every new document. CtrlSync applies one named access control list per document configuration, when the document is created; no setting chooses one by folder or by file. Error Workflow is applied instead when the document fails to come in, and Make error assignments? also creates an assignment for the owner of the connection, using the two error assignment classes.

Prevent checkouts stops users checking a document out in M-Files while its connection is active. It applies only to documents that carry a Graph ID, the ones that came from or were sent to the source, so a document that references the connection without having been synchronised can still be edited. With Prevent checkouts set to No, checking a document out in M-Files also checks the file out in SharePoint, and M-Files refuses the check-out when the file there has changed since the last synchronisation. Checking the document in sends the new version to SharePoint in the background.

No property on a document records where it may be edited; Prevent checkouts decides that for every synchronised document of the configuration.

Deleting documents

Deletion Policy decides what happens when someone deletes a document in M-Files while its connection is active, and whether CtrlSync acts on the document’s Delete on Graph property.

Deletion Policy	Deleting the document in M-Files	Setting Delete on Graph to Yes
Prevent, the default	Refused	Ignored, and the property is cleared
None	Allowed; the file in the source is left alone	Ignored, and the property is cleared
Allow	Allowed, and the file in the source is deleted too; refused when CtrlSync cannot find the file there	The file in the source is deleted; the document stays
AllowWithProperty	Refused	The file in the source is deleted; the document stays

When CtrlSync deletes a file through Delete on Graph, it removes the document’s Graph ID and, where that property is configured, sets Deleted on Graph to Yes, so the document stays in the vault with no copy in SharePoint or Teams. If the document’s Add Document to Graph is Yes, set it to No at the same time; otherwise CtrlSync uploads the document again when it is next checked in. A document whose class the Class white-list or Class black-list blocks is never deleted in the source.

Under Allow and AllowWithProperty, CtrlSync needs the file to act on. When the document has no Graph ID, because it was never synchronised or its file was removed through Delete on Graph, or when CtrlSync cannot find its file in the source, as after the file has been deleted there, deleting the document under Allow is refused, and so is saving it with Delete on Graph set to Yes.

With Prevent checkouts set to Yes, users cannot check a synchronised document out to change its properties, so they cannot set Delete on Graph either. A server process can set it while Propagate server-driven edits is No.

The policy applies only while the connection is active. When it is switched off, M-Files allows the deletion and nothing happens in the source. A connection object itself cannot be deleted while it is active, whatever the policy.

A document deleted in M-Files while its file stays in the source, under None or while the connection is switched off, comes back as a new document when its file next comes through a synchronisation, because CtrlSync does not match files against deleted documents. A file comes through when it changes in the source, and every file comes through on the first run after a connection has been off for more than 12 hours.

Properties from the connection

With Copy properties from data sources? on, a document inherits the connection object’s properties. The property white-list and black-list narrow that. CtrlSync’s own properties, such as the Graph URL, are never copied.

Black-list every property that a property mapper sets, and give each mapper a default value instead. A black-listed property is excluded even when the white-list names it.

Paths and people

Path Exclusions leaves out files in matching folders. Each exclusion has a scope and a value: scope Last with the value Excluded skips every folder named Excluded, wherever it sits in the library.

Path Property stores the document’s path in the source, and Created-by property and Modified-by property record who created and last changed it there. Both match the person’s email address in Microsoft 365 against the M-Files users, so each must be a lookup on the users value list.

Property mappings

Path Mappings, Name Mappings and Graph Property Mappings each create a property mapper when CtrlSync runs, which sets metadata from the folder a document is in, its file name, or its Microsoft Graph properties. See Property mappers.

SharePoint columns

Column Configurations writes M-Files property values into columns in the document library, so a value kept in the vault shows next to the file in SharePoint. Each entry has a Name for the column, a Column Type of Text, MultiLineText, Number, Boolean or DateTime, and the property the value comes from.

CtrlSync creates the columns in every document library of a connection when the connection object is saved while active, not on the synchronisation schedule. After adding an entry, save each connection again. Removing an entry leaves the column in place. Values are written when a document edited in M-Files is checked in, which happens only with Prevent checkouts set to No.

Nothing is read back. CtrlSync does not read SharePoint columns, so a column filled in SharePoint cannot set a class or a property in the vault. The details of a file it can turn into property values are its path, its name, who created and last changed it, and the six values a Graph property mapping offers. With Apply Automatic Metadata (Experimental) set to Yes, the values M-Files suggests from the file’s content are added as well.

Remarks

When you have finished, CtrlSync must report no local or server errors in M-Files Admin.