> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Project Templates
> Install the Nextedy PLANNINGBOARD demo project template into your Polarion instance so you can spin up a fully configured Planningboard as a starting point for new projects.
## What This Guide Covers
This guide walks through installing the bundled `planningboard_template` into Polarion's project template registry, verifying the installation through the administration interface, and creating a new project from the installed template. It also covers the template's structure so you understand what gets provisioned.
## Prerequisites
* Planningboard is installed and licensed on your Polarion instance.
* You have administrator access to the Polarion server.
* You have access to **Administration > Nextedy PLANNINGBOARD** in the Polarion admin interface.
***
1. Log in to Polarion as a system administrator.
2. Navigate to **Administration > Nextedy PLANNINGBOARD**.
3. Select the **Setup** tab.
The setup page displays the currently installed plugin version and a **Template Installation** section showing whether the demo template is already present.
If the status already shows the template as installed, skip to [Step 3](#step-3-create-a-project-from-the-template). Re-installing an already-present template is safe — the installation is transaction-wrapped and rolls back on failure — but it is unnecessary.
***
1. On the Setup page, locate the **Install Demo Template** button.
2. Click the button to trigger installation.
The server installs the template ZIP bundled with the plugin into Polarion's template repository at `.polarion/projects/templates/planningboard_template`.
The page reloads and shows a status message:
* A message beginning with `OK:` confirms a successful installation.
* Any other message indicates a failure — the installation is automatically rolled back (no partial state is left).
If you see an error message after clicking Install, check that the Polarion server process has write access to `.polarion/projects/templates/`. A permission error on the templates directory is a common cause of installation failure.
```text theme={null}
Template Installation Flow
--------------------------
Plugin ZIP (bundled)
|
v
Scan for template.properties files
(each template.properties marks one template root)
|
v
Upload each discovered template into
.polarion/projects/templates/
(wrapped in a Polarion transaction)
|
/ \
/ \
Success Failure
| |
OK: msg Rollback
(no partial state)
```
The template ZIP may contain multiple project templates. All discovered templates (each identified by a `template.properties` file at its root) are installed in a single operation.
***
Once the template is installed it appears in Polarion's standard **New Project** wizard.
1. Navigate to **Administration > Projects > Create Project**.
2. In the template picker, select **planningboard\_template** (or the display name shown after installation).
3. Fill in your project ID, name, and other required fields.
4. Complete the wizard and wait for Polarion to provision the project.
The created project includes a pre-configured LiveReport page with the Planningboard widget already added, together with example Plans, swimlane configuration, and work item types that demonstrate the board's capabilities out of the box.
The E-Library template that ships with Polarion also works well as a base for evaluating Planningboard. After creating an E-Library project, add a LiveReport page in the Planning space and insert the **Plans - Planningboard** widget. This gives you a working board without using the bundled template. See [Setup into Existing Projects](/planningboard/getting-started/setup-existing-project) for the full walkthrough.
***
1. Open the newly created project in Polarion.
2. Navigate to **Documents & Pages > Planning** (or the space configured by the template).
3. Open the **Planningboard** LiveReport page.
The board should load and display the example Plans as columns and the example work items as cards distributed across swimlanes.
| What to check | Expected result |
| ---------------------------------- | ---------------------------------- |
| Board renders without errors | Cards and column headers visible |
| Plans appear as columns | At least one column shown |
| Work items appear as cards | Cards populated in swimlanes |
| Capacity bars visible (if enabled) | Bar shown below each column header |
**Plan Name Pattern and Plan ID Pattern are pre-set for Teams.** If your project does not use the Planningboard Teams feature, update these two widget parameters on the board page before creating your first new Plan from the board. Leaving them as-is when Teams are not configured causes new Plans to be created with unexpected IDs. See [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) for the `Plan Name Pattern` and `Plan ID Pattern` fields.
***
## Template Structure Reference
The installed template provisions the following configuration:
```text theme={null}
planningboard_template/
template.properties # Template identity (required — marks the template root)
.polarion/
polarion-project.xml # Project metadata
tracker/
fields/ # Work item type and field definitions
workflow/ # Work item workflow
pages/
Planning/ # Planning space
PlanningBoard/ # LiveReport page with the widget
modules/
Planning/ # Example planning documents
```
The widget on the provisioned page has sensible defaults for `plansMode`, `assignmentMode`, `query`, `lastPlans`, and `nextPlans`. You can adjust all of these as widget parameters after the project is created.
***
## Common Pitfalls
**Whitespace in capacity configuration parameters.** If you copy widget parameter values from the template and add or remove spaces around `=` signs, capacity calculations will silently fail. Capacity configuration parameters are whitespace-sensitive — copy them exactly.
**Template visible but project creation fails.** If the template appears in the wizard but the project fails to provision, verify that the Polarion server has sufficient disk space and that the templates repository is not locked by another operation.
***
## You Should Now See
After completing this guide, the Planningboard demo template appears in Polarion's project template picker, and any project created from it opens with a working Planningboard on its LiveReport page — Plans as columns, work items as cards in swimlanes, and the widget parameters pre-configured for immediate use.
***
## See Also
* [Setup into Existing Projects](/planningboard/getting-started/setup-existing-project) — add Planningboard to a project without using the template
* [Create Your First Planningboard](/planningboard/getting-started/first-planning-board) — step-by-step board creation from scratch
* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) — full reference for all widget parameters
* [Configure Plans (Columns)](/planningboard/guides/configuration/plans-configuration) — customise which Plans appear as columns
* [Configure Swimlanes (Rows)](/planningboard/guides/configuration/swimlanes-configuration) — configure swimlane assignment type and sorting
* [Use Plan Templates](/planningboard/guides/planning/plan-templates) — configure the Template ID for new Plans created from the board
* [License Installation](/planningboard/getting-started/licensing) — if the setup page shows a license warning
**KB Articles**
* Planningboard: Customizable Statistics and Capacity Indicators
* Planningboard Widget Parameters
* How to setup Planningboard into existing projects (based on E-library template)
**Support Tickets**
* [#5879](https://support.nextedy.com/helpdesk/tickets/5879)
* [#6174](https://support.nextedy.com/helpdesk/tickets/6174)
**Source Code**
* `PlanningBoardSetupService.java`
* `PlansMode.java`
* `Config.java`
* `viewSetup.vm`
* `viewLicense.vm`