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. It points at its document object template rather than at a fixed version of a file, so what is uploaded at activation is the document template as it is at that moment. At activation, before handing the file to CtrlSync, PDS records that version on the artefact in Version Property, which keeps the copy traceable to its source 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 Generate 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 refuses the transition with a message saying what is missing, and nothing is created.

   Once the transition is saved, PDS queues the generation as a background task. The queue is polled every ten seconds, and the project stays in the Generate Baseline state until the task has run. The task creates one SharePoint artefact per document object template, in the artefact workflow’s Generated State, copying whichever properties the configuration says to copy on generate, and then moves the project to the Baseline Generated state. All of this happens inside the vault.

   If the task fails, for example because an artefact cannot be created, it writes the error to the project’s Error Property and moves the project to the Baseline Generation Error state instead. The artefacts it did create stay in 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 refuses the transition.

   The rest runs as a background task in the same way. PDS asks CtrlSync to create the folders, then hands it each artefact that is in the artefact workflow’s Generated State for upload. Properties marked to copy on activate are copied at this point rather than at generation, so they carry the value they had at upload. Each uploaded artefact moves to the Activated State, and when the folder request and every upload in the run succeed, the project moves to the Activated state.

   If anything fails, the task sets Sync Is Active Property to No, writes the error to Error Property and moves the project to the Activation Error state. An artefact that failed to upload moves to the artefact workflow’s Error State. Without a Sync Is Active Property, the task stops before it records anything on the project, and the reason is only in the PDS log.

4. Synchronisation starts.

   If a Sync Is Active Property is configured, PDS sets it, and the project’s connection begins synchronising like any other CtrlSync connection; see What a sync cycle does.

When a step fails in the background

A refused transition is seen by the person who made it. A failure in the background task is not: the transition has already succeeded, and the project changes state afterwards. Give Baseline Generation Error and Activation Error a notification or an assignment, so that someone learns of it.

Error Property holds the full error text, including the exception type and stack trace. When artefacts fail to be created or uploaded, the text names every one that failed, followed by each one’s own error. PDS never clears the property, so after a successful retry it still holds the previous error.

A failed task does not stop there. The vault application framework runs it again a minute later, and again after each further failure, up to five more times. Each run starts from the project as it stands, whatever its state, so a run that succeeds moves a project out of Baseline Generation Error or Activation Error to Baseline Generated or Activated without anyone touching it. A run that fails again overwrites Error Property. After the last run, the project stays in its error state.

A later run of either task works from what the earlier run left behind:

• A later run of baseline generation creates artefacts only for the document object templates that do not have one yet, so the artefacts that were created the first time are kept rather than duplicated.
• A later run of activation uploads only artefacts in the Generated State. An artefact that failed is in the Error State by then, so the run skips it and can move the project to Activated without that document. An Activated project can therefore still have artefacts in the Error State.

To retry, fix the cause and move the project back into the state that failed; the workflow needs a transition from each error state for that. For activation, move each artefact that is in the Error State back to Generated State first, then move the project into Activate again. An artefact left in the Error State is skipped again. A project that has already reached Activated needs a transition from there into Activate as well.

Baseline generation is only for documents

Activation creates the folders from the project template whether or not a baseline was generated. What it uploads is the artefacts that baseline generation made, so a project that reaches the Activate state without a baseline gets its folders and no documents. PDS does not enforce the order; the workflow’s transitions do.

That is why the three baseline states are optional in the configuration. A deployment that only wants a consistent folder structure leaves them empty, along with the artefact settings, and does not need document object templates, artefact objects, or the artefact type, class and workflow states that go with them. A deployment with starting documents sets all three baseline states; Set up PDS says why.

A note on “Graph Configuration”

PDS’s configuration has a section called Graph Configuration, and it contains no Microsoft Graph credentials. It names three vault properties PDS shares with CtrlSync: the SharePoint URL, which has to be filled in on the project before activation and which CtrlSync uses to reach the site; the SharePoint ID; and the active flag, which PDS sets when activation succeeds. 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 activated from it. The artefact records, in Version Property, the document template version that was uploaded, 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.