Working alongside other vault applications

A vault usually runs more than one application. CtrlShare takes hold of a document for the length of a co-authoring session, and anything else acting on that document has to expect it.

What CtrlShare holds

While a session is open, CtrlShare:

• keeps the document checked out in M-Files, to the user who started the session;
• blocks check-out by anyone else, so no other application or user can take it;
• blocks the document leaving its workflow state, whether a user tries or an automatic state transition does.

The last one is the part that surprises people. A state transition that would normally fire on a schedule or on a property change will not fire while the document is being co-authored. It is not lost — it happens once the document is checked back in.

What this means for automation

An automatic workflow transition, a scheduled job, or another vault application that expects to modify a document will find it locked for as long as the session lasts. Sessions are open-ended: a document stays out until someone runs Check In or Undo Check Out.

If a document can get stuck — the person who started the session has left, for example — an administrator can undo the check-out from M-Files Admin.

Starting a session from a workflow

Rather than having automation fight the lock, drive the session from the workflow itself. A workflow mapping names a state that, when a document enters it, checks the document out to co-authoring and shares it with the people named by the properties you choose. The document then cannot leave that state until it is checked back in, which is what makes the review step reliable rather than advisory.

That is the supported way to combine CtrlShare with a controlled process.

CtrlShare and CtrlSync in the same vault

Both applications can be installed in the same vault, and most of the time they do not meet. CtrlSync keeps documents in step with SharePoint and Teams; CtrlShare hands a document to OneDrive so several people can edit it together. They collide only over a document that both are configured to act on.

Where they do collide, the document exists in two places outside the vault for the length of the session — the OneDrive copy people are typing into, and the SharePoint or Teams copy CtrlSync is keeping in step — and whichever side writes last wins. A document that is co-authored in OneDrive and synchronised to a Teams channel is being edited in two places by design, and no setting makes that safe. The answer is to give each document class to one application.

Finding the overlap

Compare the classes CtrlSync acts on against the documents CtrlShare is allowed to check out. If the two sets do not intersect, there is nothing to do.

On the CtrlSync side that is its document configurations: the connection source class, and the class white-list or black-list that limits which classes its property mappers may derive.

On the CtrlShare side it is Access Control, whose search conditions decide which documents may be checked out for co-authoring at all. It is open by default — with no conditions configured, every document CtrlShare can handle is eligible — so a vault running both applications should not leave it that way. Where the conditions do not match a document, the co-authoring commands are not offered on it.

What happens when they overlap

Two behaviours matter, and they are not the same behaviour.

CtrlSync’s Prevent checkouts, which is on by default on a document configuration, refuses any check-out of a document attached to an active data source. CtrlShare’s Check Out to OneDrive is an ordinary M-Files check-out, so it is refused as well, and the user is told that the document is currently maintained by an active data source. That is the better of the two outcomes: the conflict is stopped at the moment somebody tries to start a session, rather than discovered later.

With Prevent checkouts turned off, the session starts, and CtrlSync then skips the document because it is checked out and picks it up on the next cycle. That is enough for an editing session that lasts an afternoon. It is not enough for one that lasts days, and CtrlShare sessions are open-ended.

Separating the two

Narrow CtrlSync’s document configurations so they do not cover the classes CtrlShare handles, or keep co-authored documents out of the connections CtrlSync synchronises. Then confirm it on one document of each kind: a co-authored class should check out to OneDrive and come back through Check In with no CtrlSync cycle having touched it, and a document on a CtrlSync connection should not offer the co-authoring commands at all.

There are no check-out hooks

The previous documentation described an EventConfiguration: four lists of vault extension methods to call around a session — BeforeCheckOutActions, AfterCheckOutActions, BeforeCheckInActions and AfterCheckInActions — used to call CtrlSync.CheckOut and CtrlSync.CheckIn, so that checking a document out to OneDrive also checked it out in SharePoint.

CtrlShare 2.26.8.0 has no such settings and no equivalent. Separating the two applications by class, as above, is the way to run them side by side. If a deployment relies on that interlock, raise it with CtrlDocs support before upgrading rather than assuming an equivalent exists.