About CtrlSync

CtrlSync works from connection objects. Each one names a SharePoint site or a Teams channel, and says which documents in the vault belong to it. Everything else follows from that.

What a sync cycle does

On each run, for every active connection, CtrlSync asks Microsoft Graph what has changed since last time and brings new and modified files into the vault. Changes go the other way outside the run, as they happen in M-Files: a document that belongs to an active connection but has no file in the source yet is uploaded when it is checked in with Add Document to Graph set to Yes, a file is deleted in the source when the Deletion Policy provides for it, and, where Prevent checkouts is No, a document checked in after an edit is sent back in the background. Documents are matched by an identifier stored on the M-Files object, not by name, so renaming a file on either side does not create a duplicate.

Work happens in batches. Starting the job queues the next batch; at the end of a batch it queues another, until there is nothing left. That is why a large first synchronisation keeps going after the scheduled window has passed — it has not stalled, it is still working through the queue.

What happens when…

CtrlSync finds the M-Files document for a file by the file’s Graph ID together with the connection the document belongs to, and looks only at documents that have not been deleted in M-Files. Most of what follows comes from that rule.

A file is deleted or restored in SharePoint or Teams

The M-Files document is not deleted. CtrlSync sets its Deleted on Graph property to Yes and brings no further changes to it while the file stays deleted. Without that property configured, nothing in the vault shows that the file has gone.

If the file is restored from the recycle bin, the next run sets Deleted on Graph back to No, and the document is updated from the source again as before.

A file is moved

Moved to another folder in the same document library, one its connection synchronises, a file keeps its document. CtrlSync updates Path Property and Graph JSON Data, renames the document if the file name changed and the class does not name documents automatically, and runs again every property mapper whose Set once? is No. Path and name mappings default to Yes, so a file moved into a folder that maps to another class keeps the class it arrived with. Set Set once? to No on that mapping for the class to follow the folder.

Moved into a folder that belongs to a different connection, such as another channel’s folder where each channel is its own connection, the file arrives as a new document under that connection. The document the file had before stays in the vault.

A connection is switched off

Setting Data Source ‘Active’ to No makes CtrlSync queue one last synchronisation of that connection. It reads every file in the source rather than only the recent changes, so nothing added shortly before the switch is missed, and then leaves the connection alone.

While the connection is off, nothing moves in either direction. Prevent checkouts and Deletion Policy no longer apply to its documents, so they can be edited and deleted in M-Files, and none of that reaches SharePoint or Teams while the connection stays off.

Switched on again, the connection brings in the files added or changed in the source while it was off. Where the same file changed on both sides, the SharePoint content becomes the newest version in M-Files, and the M-Files edit survives only in the document’s history. Switching the connection on sends no document from M-Files. Any other edit made there in the meantime reaches SharePoint or Teams with the document’s next check-in where Prevent checkouts is No, which sends the whole file, and a Delete on Graph set in the meantime is acted on at the document’s next check-in. A document deleted in M-Files in the meantime comes back as a new document when its file next comes through a synchronisation, and every file comes through if the connection was off for more than 12 hours.

The configuration changes

A changed document configuration is not applied to the vault in one pass. Each setting takes effect at its own point:

• Default Document Class, Default Workflow and Default Named Access Control List are applied when a document is created. Existing documents keep what they were given, except that a document whose update from the source cannot be saved is set to the Default Document Class and, where one is set, the Error Workflow.
• A property mapper whose Set once? is Yes, the default for path and name mappings, also runs only when a document is created. One set to No runs again every time the file comes through a synchronisation.
• Copy properties from data sources? fills in properties a document has no value for, and never overwrites one. A value changed on the connection object does not reach documents that already carry the old one.
• A class blocked by the Class white-list or Class black-list, or a folder added to Path Exclusions, stops files coming in. Documents already in the vault stay where they are and are no longer updated from the source.

A file comes through a synchronisation when it changes in the source, and when CtrlSync reads a whole document library again: on the final synchronisation after a connection is switched off, on any run more than 12 hours after the library was last read successfully, and after the library could not be read or one of its files failed. In that last case CtrlSync also sets Data Source ‘Error’ to Yes, which pauses the whole connection, and reads the library on the first run after the check at the Maintenance Frequency has set it back to No. A file skipped under the old configuration is imported then, if the new one allows it.

A team, channel or SharePoint site is archived

For a team or channel connection, CtrlSync asks Microsoft Graph on every run whether the team is archived. If it is, the run writes Source '…' has been archived and can no longer be synchronized. to the CtrlSync log and carries on. CtrlSync does not switch the connection off; set Data Source ‘Active’ to No when the team is retired.

An archived channel is not noticed, because CtrlSync asks about the team rather than the channel. The connection goes on synchronising.

A SharePoint site has no archived state in CtrlSync. It is synchronised for as long as Microsoft Graph returns it. When Graph stops returning it, CtrlSync sets Data Source ‘Error’ to Yes, writes This data source could not be found in the connected graph. to Data Source Status where that property is configured, and checks the connection again at the Maintenance Frequency.

What it does not do

• It is not a live sync. Changes in the source come in on a cycle, not the moment they happen. A very short interval strains the M-Files server without making the result meaningfully fresher.
• It does not co-author. Simultaneous editing of one document is CtrlShare, which is a different mechanism.
• It does not create Teams. Finding and creating teams and channels is CtrlTMS.
• It does not move permissions. M-Files permissions govern the vault copy; SharePoint permissions govern the SharePoint copy. Neither is derived from the other.

Deleting on one side

Deleting a file in SharePoint or Teams never deletes its M-Files document. Deleting a document in M-Files deletes the file in SharePoint or Teams only when the connection’s Deletion Policy is Allow; see Deleting documents.