About PDS

PDS is built around five kinds of object in the vault. Four of them are things an administrator sets up once; the fifth is created by PDS as it works. Everything in the configuration is a pointer to one of them.

The objects

Path objects each describe one folder. A path holds a partial title — the folder’s own name — and a reference to its parent, so a hierarchy of folders is a chain of path objects rather than a string somebody typed. A folder’s full path is derived by walking the chain.

A project object template is the blueprint for a kind of project. It names the directory structure the project should get, and lists the document object templates it should start with.

Document object templates sit between a project template and a document. Each one names the document template to copy, and the path object saying which folder the copy belongs in. It is the join between “what document” and “where it goes”.

Document templates are ordinary M-Files documents with a file attached. This is the file that ends up in SharePoint.

SharePoint artefacts are created by PDS, one per document object template, when a project’s baseline is generated. An artefact is a document that has not been uploaded yet, and it records which version of the template it was made from — so the copy stays traceable to its source even after the template changes.

Templates are usually one object type, several classes

Project object templates and document object templates are normally the same object type — an Object Templates type — separated by class. Nothing requires that; it is how these deployments are usually built, and it keeps the templates together in one place in the vault.

What happens, in order

1. A user creates a project and points it at a template.

   The project’s Template Property references a project object template. Nothing has happened yet.

2. The project enters the baseline state.

   PDS validates the template before doing anything: the project needs a template, the template needs a directory structure, and every document object template needs a directory structure, a full path and a document template. A missing one fails the transition with a message naming the object.

   PDS then creates one SharePoint artefact per document object template, copying whichever properties the configuration says to copy on generate. All of this happens inside the vault.

3. The project enters the activate state.

   PDS checks that CtrlSync is installed, configured and licensed, and that a SharePoint URL is set on the project. Either check failing stops the transition.

   It then hands the folder structure and each artefact to CtrlSync, which creates the folders and uploads the files. Properties marked to copy on activate are copied at this point rather than at generation, so they carry the value they had at upload.

4. Synchronisation starts.

   If a Sync Is Active Property is configured, PDS sets it. The project’s connection begins synchronising like any other CtrlSync connection, and from then on the folder is a normal two-way synchronised location.

Baseline generation is not optional

The two workflow states for baseline generation are marked optional in the configuration, and that is misleading. Without the baseline step nothing is created and no files appear — PDS does its work there.

What is optional is the artefact half of it. A deployment that only wants a consistent folder structure, with no starting documents, does not need document object templates, artefact objects, or the artefact type, class and workflow states that go with them. Leave the artefact settings empty and PDS creates folders only.

A note on “Graph Configuration”

PDS’s configuration has a section called Graph Configuration, and it contains no Microsoft Graph credentials. It holds three vault properties — the SharePoint URL, the SharePoint ID and the active flag — that PDS writes and CtrlSync reads. The name is the one shown in M-Files Admin, so this documentation keeps it, but it is the CtrlSync hand-over rather than an Azure connection.

What it does not do

• It does not talk to Microsoft. Every call to SharePoint is made by CtrlSync, with CtrlSync’s credentials. PDS has no Entra ID settings of its own.
• It does not keep projects in step with their template. Changing a project template does not change projects already generated from it. The artefact records the template version it was made from precisely because the two diverge.
• It does not decide what happens to later edits. Whether a change made in SharePoint to an uploaded document is kept or discarded is the Default Synchronization Behavior setting, and the condition beside it, both of which CtrlSync acts on.