How an object moves through CtrlTeams

The three applications never call each other directly. They meet on M-Files objects: one application writes a property or moves an object into a workflow state, and the next one is watching for exactly that. Knowing which application is responsible at each step is what makes a stalled deployment diagnosable.

A team that already exists in Microsoft 365

1. CtrlTMS finds the team.

   On its schedule, CtrlTMS asks Microsoft Graph what teams and channels exist. For each one it does not already have, it creates an M-Files object.

   The object it creates is a connection object — the same object type and class CtrlSync works from. This is the join between the two applications, and it is a configuration choice rather than something either application does on its own.

2. The connection waits, inactive.

   Create connections with synchronisation switched off. A team discovered automatically has not yet been reviewed: nobody has decided which class its documents should get, which workflow they belong in, or whether it should be synchronised at all.

   The object sits in a workflow state that means found, not yet approved, and no files move.

3. Someone approves it.

   A vault administrator checks the connection’s settings and moves it to the active state. A state action on that transition sets CtrlSync’s Data Source ‘Active’ to Yes. On a team, it also has to set CtrlTMS’s Active Property to Yes where that is a different property. Discovery leaves Active Property empty, and CtrlTMS brings changes from Microsoft Teams into the vault, and sends vault changes to Microsoft Teams, only for a team whose Active Property is Yes.

   From CtrlSync’s point of view nothing special happened — a connection became active, which is the only signal it needs.

4. CtrlSync starts synchronising.

   On its next run, CtrlSync sees an active connection it has not synchronised, and works through the channel’s files in batches. From then on, each cycle brings in the changes made in the channel, and, where Prevent checkouts is No, a document checked in after an edit in M-Files is sent back in the background.

5. CtrlTMS keeps the membership in step.

   Independently of the files, the CtrlTMS down-sync, which runs on its Down-sync interval, keeps the team’s owners and members up to date on the M-Files object, so the vault can answer who has access to the team without asking Microsoft.

A project that starts in M-Files

This is the path PDS adds. It runs before the one above rather than instead of it.

1. A user creates a project and picks a template.

   The project object references a project template, which lists the document object templates it should start with and the directory structure it should have.

2. The project enters the baseline state.

   PDS checks that the template is complete — every document object template needs a directory structure, a full path and a document template — and refuses the transition with a specific message if any of that is missing.

   It then creates one SharePoint artefact object per document object template. Nothing has been sent to Microsoft yet; this all happens inside the vault.

3. The project is activated.

   PDS requires a SharePoint URL on the project before it will allow this, and it checks that CtrlSync is installed, configured and licensed. If either is missing the transition fails and says which.

4. CtrlSync uploads the folders and files.

   PDS hands each artefact to CtrlSync, which creates the folders and uploads the documents. Each uploaded artefact records, in Version Property, the version of the document template that was uploaded.

5. PDS switches synchronisation on.

   If a Sync Is Active Property is configured, PDS sets it, and the project’s connection begins synchronising like any other.

Where to look when it stalls

The step that failed tells you which application to look at. Nothing happened after a team appeared in Microsoft 365 — CtrlTMS. Objects were created but no files moved — CtrlSync, or a connection that was never made active. A project would not enter the baseline state — PDS, and the message on the refused transition names what the template is missing. A project that moved to the baseline generation or activation error state has the reason in its Error Property.

A team created in M-Files

CtrlTMS can also turn an object in the vault into a new team. The workflow drives it, and CtrlSync joins in only once the team exists.

1. Someone fills in the team object.

   It needs a display name and at least one owner. Only people whose person object has an email address count, as owners or as members; the others are left out of the team. CtrlTMS refuses to move a team into Create State without a display name, or a private team without an owner. A public team without an owner is saved, but its creation fails and it goes to Error State. Channels are objects of the channel class that reference the team, and two channels of one team cannot share a name.

2. The object moves into the Create State.

   Entering Create State queues the creation as a background operation, provided the object has no Graph ID yet. The object is saved straight away and the team appears in Microsoft Teams shortly after.

3. CtrlTMS creates the team.

   It creates the team, adds the members and owners, and creates each channel. A channel whose name matches one the new team already has, such as General, is linked to it rather than created a second time. When all of that succeeds, CtrlTMS sets the team’s Active Property to Yes and moves it to Created State. If any of it fails, the team goes to Error State with Active Property set to No. Moving a team from Error State back into Create State does not create it again once it has a Graph ID; see Workflow.

4. CtrlSync starts when its own switch is on.

   CtrlSync reads Data Source ‘Active’, not CtrlTMS’s Active Property, so with the two kept apart the new team waits for approval like a discovered one. Pointing both at the same vault property starts it synchronising on CtrlSync’s next run, and is safe only where teams and channels are separate object types. CtrlTMS reads Active Property on every object of the team object type. With one object type for both, as Vault structure recommends, a channel connection switched on for CtrlSync then counts as an active team: CtrlTMS checks it against the rules for a team when it is saved, and sends its changes to Microsoft Teams as team changes, which fail. The down-sync also reads it as a team, which fails and is logged on every run. In that layout, keep the two properties apart. A team CtrlTMS creates gets its Active Property from CtrlTMS; a discovered team gets it from the state action that approves it, as in A team that already exists in Microsoft 365. No state action may set Active Property on a channel.

   CtrlSync finds the team through its Graph URL property, which has to be the property CtrlTMS writes as Graph URL Property. CtrlTMS writes it for the team when it creates the team, but a channel it creates or links gets its Graph URL only on the next CtrlTMS down-sync, so the channel’s connection cannot start synchronising before then.

A channel object added later to a team whose Active Property is Yes is created in Microsoft Teams in the same way, or linked to an existing channel of the same name.

When a team or channel ends

Neither application archives or deletes a team or channel in Microsoft Teams, and neither acts on its own when Microsoft 365 archives one. Ending a team is a decision made in the vault.

A team archived in Microsoft Teams stays as it is in the vault. CtrlTMS does not read the archived flag and goes on down-syncing the team. CtrlSync does read it: every run of the team’s connections writes a warning to the CtrlSync log, but the connections stay active.

To retire the team, move its object into the Archived State, and set Data Source ‘Active’ to No on the team and on each of its channel connections. A state action on the transition into the Archived State can set the team’s own Data Source ‘Active’ to No; the channels are separate objects and each needs it set. The Archived State takes the team out of the CtrlTMS down-sync, but it does not stop changes made in the vault being sent to Microsoft Teams. Where CtrlTMS’s Active Property is a different property from Data Source ‘Active’, set it to No on the team as well. Switching Data Source ‘Active’ off makes CtrlSync read the connection once more, in full, and then stop.

A team deleted in Microsoft Teams stays as it is in the vault. While its Active Property is Yes, the CtrlTMS down-sync of it fails on every run and is logged as a failure, and moving it into Deleted State does not change that. If the team’s connection is switched on, CtrlSync sets Data Source ‘Error’ on it, and the team’s active channel connections fail on each run. Set Active Property and Data Source ‘Active’ to No on the team, and Data Source ‘Active’ to No on each channel connection.

A channel archived in Microsoft Teams is not noticed by either application. CtrlSync checks whether the team is archived, not the channel, so the channel’s connection goes on synchronising until it is switched off.

A channel deleted in Microsoft Teams has to be switched off and deleted in the vault. Once Microsoft Graph no longer returns the channel, its connection fails on each CtrlSync run, and the CtrlTMS down-sync of its whole team fails too: before it applies any change, the down-sync reads every channel object of the team from Microsoft Graph. Every run for that team is written to the CtrlTMS log as a failure, and no name, member or channel changes for the team come down until the channel’s object is gone. CtrlSync blocks the deletion of an object that is an active connection, so set the channel’s Data Source ‘Active’ to No first, then delete its object in the vault.

Switching off in the vault changes nothing in Microsoft Teams. A team whose Active Property is No is left out of the CtrlTMS down-sync, and changes made to it or to its channels in the vault are no longer sent to Microsoft Teams. Setting a channel’s Active Property to No does not stop CtrlTMS sending its changes; only the team’s does. For what switching Data Source ‘Active’ off does in CtrlSync, see A connection is switched off.

Where the applications agree

The join	Written by	Read by
Connection object type and class	CtrlTMS creates them	CtrlSync synchronises them
CtrlSync’s Graph URL property	CtrlTMS (Graph URL Property): on discovery, when it creates a team, and on the down-sync for a channel added in Microsoft Teams and for any channel that has none, including one it creates or links. For a PDS project, whoever fills in the project, before activation	CtrlSync, to find the site, team or channel. PDS (SharePoint URL Property), which refuses activation while it is empty
Connection active property	The workflow state action, or PDS	CtrlSync
Employee or person object	CtrlSync and CtrlTMS both resolve users through it	Both

Each of these is a setting in two or more places that has to name the same thing. They are the first place to look when two of the applications appear to disagree about the same object.