Build a project template

A project template is built from the bottom up: folders first, then the documents that go in them, then the template that collects the lot. Building it in that order means every reference points at something that already exists.

This guide builds a small onboarding template — three folders and one starting document — which is the right size for the first one on a new deployment.

Before you start

PDS installed and configured, with the project, path and document template sections filled in. The application status in M-Files Admin should report no configuration errors.

Steps

1. Create the folders as path objects.

   Create one path object per folder. In each, put the folder’s own name — not its full path — in the partial path title property, and its parent folder in the directory structure property. A top-level folder has no parent.

   For the onboarding example: Contracts, Correspondence and Deliverables, each with no parent.

   The partial path title is one folder's name

   Putting Contracts/Signed in a partial path title produces a folder with a slash in its name, not two folders. A nested folder is a second path object whose parent is the first.

2. Create the document template.

   Create an ordinary M-Files document with the file to be copied attached — the blank engagement letter, the standard agenda. This is a real document in the vault, and it is what ends up in SharePoint.

3. Create a document object template for it.

   This is the object that joins a document to a folder. On it, set:

   • the document template property to the document created in the previous step;
   • the full path property to the path object for the folder the copy belongs in;
   • the directory structure property.

   All three are required. A missing one refuses the transition into the Generate Baseline state, with a message naming this object.

4. Create the project object template.

   Set its directory structure property to the folder structure the project should get, and its document object templates property to the document object template created above. Add more document object templates here as the template grows.

5. Point a project at the template.

   Create a project object and set its template property to the project object template.

6. Generate the baseline.

   Move the project into the Generate Baseline state. PDS validates the template first. If anything is missing, the transition is refused with a message saying what is missing, and nothing has been created: fix it and try the transition again.

   Once the transition succeeds, PDS creates one SharePoint artefact per document object template in the background, then moves the project to Baseline Generated. If that fails, the project moves to Baseline Generation Error instead, and Error Property on the project says why. PDS runs the generation again a minute later, up to five more times, and a run that succeeds moves the project on by itself. If the project stays in the error state, fix the cause and move it back into Generate Baseline: PDS then creates artefacts only for the document object templates that still have none.

7. Activate the project.

   Set the project’s SharePoint URL property, then move the project into the Activate state. PDS hands the folders and artefacts to CtrlSync in the background. The project moves to Activated when the folder request and every upload succeed. A failure moves the project to Activation Error with the reason in Error Property, and moves each artefact whose upload failed into the artefact workflow’s Error State.

   PDS runs activation again a minute later, up to five more times. A run uploads only artefacts in Generated State, so it skips the ones that failed, and one of those runs can move the project to Activated without them. To retry a failed document, fix the cause, move its artefact from Error State back to Generated State, and move the project into Activate again. Without a Sync Is Active Property, a failed activation records nothing on the project and the reason is only in the PDS log.

Check

• The three folders exist in the SharePoint site, nested as the path objects describe.
• The engagement letter is in Contracts, with the name the title placeholder produced and the content of the document template.
• The artefact’s Version Property names the version of the document template that was uploaded.

Naming the uploaded documents

By default an artefact is titled after its document object template. The TitlePlaceholder setting changes that: it accepts property placeholders such as {Name} or {Title}, expanded when the document is created. A placeholder naming a property the object does not have produces an empty value rather than an error, so check the result on the first upload.

Growing the template

Adding a document object template to a project template affects projects generated from then on. Projects already generated keep the artefacts they were given, and PDS does not go back and revise them. Once an artefact has been uploaded, its Version Property records which version of the document template went up.

To give an existing project a document it did not start with, add it to the project directly.