Set up PDS

By the end of this section a project created from a template generates its folders and its starting documents in SharePoint.

Time: two to three hours, once CtrlSync is working. Most of it is building the vault structure, not configuring PDS.

Who you need: someone with administrative access to the vault through M-Files Admin. No Microsoft 365 administrator is needed for PDS itself — it reaches SharePoint through CtrlSync, using CtrlSync’s credentials.

Before you start

• CtrlSync installed, configured, licensed, and demonstrably synchronising one connection. PDS calls into it and refuses to activate a project when it cannot.
• M-Files 23.6.0.0 or later, and administrative access to the vault.
• The PDS .mfappx file and its .lic licence file.
• An agreed window for a vault restart.
• A decision about whether the deployment needs starting documents or only folders. A folders-only deployment skips the artefact settings entirely.

Steps

1. Install the application and its licence.

   Follow Install a vault application, then Install a vault application licence.

   Without a licence the check-in handler that drives everything is disabled, and the log says so on startup.

   Check: PDS appears under the vault’s Applications node and the vault has been restarted.

2. Create the vault structure.

   Every setting in the PDS configuration points at an object type, class, property, workflow or state that has to exist first. See Vault structure.

   Check: you can create a path object, a project object template and a document object template by hand, and link them to each other.

3. Configure the project and path sections.

   Point PDS at the project object type and class, the property that links artefacts and documents to a project, and the property holding the project’s template. Name a multi-line text property as Error Property: when baseline generation or activation fails after its transition, PDS writes the reason there. Then do the same for paths: the path object type, the partial path title, the full path and the directory structure property.

   Check: M-Files Admin shows no validation error against the project and path settings.

4. Configure the workflow.

   Name the project workflow and its states. Activate, Activated and Activation Error are required. Generate Baseline, Baseline Generated and Baseline Generation Error are needed only when the deployment creates starting documents, and then all three are. With Generate Baseline set, an empty Baseline Generated moves a project whose generation succeeded to the first state of the workflow, and an empty Baseline Generation Error does the same to a project whose generation failed.

   Both error states are entered by a background task after the transition that started it has succeeded, so the person who moved the project is not told. Give each error state a notification or an assignment, and a transition back into the state that failed so the project can be retried.

   Check: the states named in the configuration are the ones on the project workflow, the workflow has a transition into Generate Baseline and a route from Baseline Generated to Activate (only a transition into Activate in a folders-only deployment), and each error state has a transition back.

5. Configure the hand-over to CtrlSync.

   In Graph Configuration, name the property holding the project’s SharePoint URL, the one holding its SharePoint ID, and the active flag in Sync Is Active Property, which PDS sets when activation succeeds so that synchronisation starts by itself. Set Sync Is Active Property in every deployment: without it, a failed activation writes nothing to Error Property and never reaches Activation Error.

   The URL property has to be the one CtrlSync reads on its connections. This is the single setting that most often stops a working-looking deployment from producing anything.

   Check: the property named here is the same one named in CtrlSync’s configuration. In a folders-only deployment, the application status in M-Files Admin now reports no configuration error.

6. Configure document templates and artefacts.

   Skip this step if the deployment only needs folders.

   Name the artefact object type and class, the property linking an artefact to its document object template, and the property holding the document template on a document object template. Name the artefact workflow and its Generated State, Activated State and Error State. Activation uploads only artefacts in Generated State. Give the artefact workflow a transition from Error State back to Generated State, so that a failed artefact can be uploaded again. Set Version Property as well: it records which version of each document template was uploaded, and although the configuration marks it optional, every upload fails while it is empty. Decide what happens to later edits with Default Synchronization Behavior.

   Check: the application status in M-Files Admin reports no configuration error. PDS refuses to run its handlers at all while the configuration is invalid.

7. Build one template and run it end to end.

   See Build a project template.

   Check: a project created from the template generates its artefacts, activates, and its folders and documents appear in SharePoint under the expected names.

Test with one document, not twenty

The first template to build is one project template with a single document object template. Every configuration mistake shows up on the first one, and a template with twenty documents produces twenty copies of the same error.

If something goes wrong

See Troubleshooting. PDS puts its reason on the workflow transition it refused, or, when the background work fails after the transition, in the project’s Error Property. Read the message before anything else — it usually names the object that is incomplete.