> ## 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.

# Use Plan Templates

> Configure name and ID patterns so Nextedy PLANNINGBOARD creates consistently structured Plans from a single click — no manual naming required.

## What this guide covers

When you enable the **New Plan** feature in widget parameters, Planningboard generates new Plans from a template. This guide shows you how to configure the template parameters — name pattern, ID pattern, duration, parent, and optional team expansion — so every new Plan follows your project's naming conventions.

## Prerequisites

* Planningboard widget already embedded in a Polarion LiveDoc or Wiki page
* Widget parameters accessible (page editor or administration)
* At least one existing Plan in the project (auto-numbering extracts the sequence start from the last matching Plan)

***

<Steps>
  <Step title="Enable the New Plan feature">
    1. Open the page containing your Planningboard widget and enter edit mode.
    2. Open the widget parameters panel.
    3. Locate the **New Plan** section and enable it.

    Once enabled, a **plus (+) button** appears in the board toolbar. Until you configure the template parameters (steps below), clicking it creates Plans with default values — proceed to the next steps to control naming and structure.

    ***
  </Step>

  <Step title="Set the Template ID">
    The `Template ID` parameter tells Polarion which plan template to use (for example `iteration` or `release`). This controls the Plan type that gets created.

    ```properties theme={null}
    Template ID: iteration
    ```

    <Warning title="Match your project's plan template IDs">
      The value must match an existing Polarion plan template ID in your project, not a display name. Using an incorrect ID silently creates a Plan of the wrong type or causes creation to fail.
    </Warning>

    ***
  </Step>

  <Step title="Configure name and ID patterns">
    Two pattern parameters control what the new Plan is called and what identifier it receives:

    | Parameter           | Purpose                              | Available placeholders    |
    | ------------------- | ------------------------------------ | ------------------------- |
    | `Plan Name Pattern` | Display name shown in column headers | `{planNum}`, `{teamName}` |
    | `Plan ID Pattern`   | Unique identifier in Polarion        | `{planNum}`, `{teamId}`   |

    The `{planNum}` placeholder is replaced by an auto-incremented integer. Planningboard determines the next number by:

    1. Querying for existing Plans matching the same template ID and project.
    2. Extracting `{planNum}` from the last matching Plan's ID.
    3. Incrementing by 1.
    4. Defaulting to `1` if no matching Plans are found.

    ### Example — single-team iterations

    ```properties theme={null}
    Plan Name Pattern: Iteration {planNum}
    Plan ID Pattern:   iteration_{planNum}
    ```

    This produces Plans named **Iteration 4**, **Iteration 5**, etc., with IDs `iteration_4`, `iteration_5`.

    ### Example — SAFe-style naming with dashes

    ```properties theme={null}
    Plan Name Pattern: I-{planNum}
    Plan ID Pattern:   I-{planNum}
    ```

    <Warning title="Dash characters in plan names require version 25.3.0 or later">
      A parsing bug in earlier versions caused column spans to render incorrectly, capacity to show zero, and plan shortcuts to disappear when plan names contained dashes (for example `I-2401-1` or `PI-2401`). If you use dash-containing naming patterns, confirm you are running version 25.3.0 or later before relying on this feature in production.
    </Warning>

    ***
  </Step>

  <Step title="Set a Parent Plan (optional)">
    If your project contains multiple release versions and you want new iterations created under a specific parent, set the `Parent ID` parameter:

    ```properties theme={null}
    Parent ID: Version_3_0
    ```

    Leave this blank to place new Plans at the root level of the project.

    <Tip title="Use Parent ID when multiple versions exist">
      Without a Parent ID, Planningboard looks for the most recent Plan of the same template type anywhere in the project. If multiple versions are active, new Plans may be placed under the wrong parent. Specifying Parent ID ensures consistent placement.
    </Tip>

    ***
  </Step>

  <Step title="Set the Plan duration">
    `New Plan Duration` defines how long each generated Plan spans. Enter the duration in days:

    ```properties theme={null}
    New Plan Duration: 14
    ```

    Planningboard calculates the start date of the next Plan by looking for the last Plan matching your template and project (using `Last Plan Query` and `Last Plan Sort` if configured), then placing the new Plan immediately after it.

    **Date calculation fallback sequence:**

    ```text theme={null}
    1. Use nextStartDate if explicitly provided (YYYY-MM-DD)
            |
            v
    2. Find last plan via Last Plan Query + Last Plan Sort
       (default sort: latest dueDate)
            |
            v
    3. Calculate new start = last plan's end date + 1 day
            |
            v
    4. Calculate new end = new start + New Plan Duration
    ```

    If no previous Plan is found, the system falls back to the parent Plan's start date, then today's date.

    ***
  </Step>

  <Step title="Configure Last Plan Query (optional)">
    By default, Planningboard finds the "last plan" by querying all Plans in the project with the same template ID, sorted by due date (latest first). You can override this with a custom Lucene query:

    ```properties theme={null}
    Last Plan Query: projectId:MyProject AND type.id:iteration
    Last Plan Sort:  dueDate
    ```

    Leave both blank to use the default behavior.

    ***
  </Step>

  <Step title="Enable Teams (optional)">
    If your board uses multiple teams, enable the **Enable Teams** option and define team name/ID pairs. When Teams are enabled, clicking the plus (+) button creates one new Plan per team in a single operation.

    ```properties theme={null}
    Enable Teams: true
    Teams:
      - name: Alpha Team
        id:   alpha
      - name: Beta Team
        id:   beta

    Plan Name Pattern: {teamName} - Iteration {planNum}
    Plan ID Pattern:   {teamId}_iteration_{planNum}
    ```

    This produces Plans named **Alpha Team - Iteration 4** and **Beta Team - Iteration 4** simultaneously.

    <Warning title="Predefined patterns include {teamName} / {teamId} by default">
      When you enable Teams, the widget pre-populates the name and ID patterns with `{teamName}` and `{teamId}` placeholders. If your project does not use teams, remove these placeholders — otherwise `{teamName}` and `{teamId}` appear as literal text in your Plan names.
    </Warning>

    ***
  </Step>

  <Step title="Create a Plan">
    1. Save the widget parameters.
    2. Return to the board view and click the **plus (+) button** in the toolbar.
    3. A confirmation dialog appears showing the calculated values (name, ID, dates, parent).
    4. Review the values and confirm.

    The new Plan appears as a column on the board immediately after the page refreshes.

    <Tip title="Review values in the confirmation dialog before creating">
      The confirmation dialog shows what Planningboard calculated for name, ID, start date, and end date. If the values look wrong (wrong sequence number, unexpected parent), cancel and check your pattern configuration before proceeding.
    </Tip>

    ***
  </Step>
</Steps>

## Verification

You should now see:

* The new Plan column in the board with the name matching your `Plan Name Pattern`.
* The Plan ID in Polarion matching your `Plan ID Pattern` with the correct sequence number.
* The Plan's start and end dates consistent with the previous Plan's end date plus the configured duration.
* If Teams are enabled, one column per team created in a single operation.

If the column does not appear, use the **Refresh data** toolbar button to reload the board without a full page reload.

***

## Configuration summary

| Parameter           | Required | Example               | Notes                                                    |
| ------------------- | -------- | --------------------- | -------------------------------------------------------- |
| `Template ID`       | Yes      | `iteration`           | Must match an existing Polarion plan template ID         |
| `Plan Name Pattern` | Yes      | `Iteration {planNum}` | Uses `{planNum}`, `{teamName}`                           |
| `Plan ID Pattern`   | Yes      | `iteration_{planNum}` | Uses `{planNum}`, `{teamId}`                             |
| `Parent ID`         | No       | `Version_3_0`         | Scopes new Plans under a specific parent                 |
| `New Plan Duration` | Yes      | `14`                  | Duration in days                                         |
| `Last Plan Query`   | No       | `type.id:iteration`   | Lucene query to find the anchor Plan                     |
| `Last Plan Sort`    | No       | `dueDate`             | Field used to pick the "last" Plan; default is `dueDate` |
| `Enable Teams`      | No       | `true`                | Creates one Plan per team on each click                  |

***

## See also

* [Bulk Plan Creation](/planningboard/guides/planning/bulk-plan-creation) — create multiple Plans at once via script
* [Create Plans](/planningboard/guides/planning/creating-plans) — manually create and manage Plans on the board
* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) — full reference for all widget parameters
* [Configure Plans (Columns)](/planningboard/guides/configuration/plans-configuration) — control which Plans appear as columns
* [SAFe Plan Naming Conventions](/planningboard/guides/planning/safe-naming-conventions) — naming patterns for SAFe hierarchies
* [SAFe Planning Workflows](/planningboard/guides/planning/safe-planning) — end-to-end SAFe configuration guide

<Accordion title="Sources">
  **KB Articles**

  * Introduction to Planningboard
  * Planningboard interface & basic interactions
  * Planningboard Widget Parameters

  **Support Tickets**

  * [#5879](https://support.nextedy.com/helpdesk/tickets/5879)
  * [#6174](https://support.nextedy.com/helpdesk/tickets/6174)
  * [#4711](https://support.nextedy.com/helpdesk/tickets/4711)

  **Source Code**

  * `PlanningBoardWidgetRenderer.java`
  * `Item.java`
  * `PlansMode.java`
  * `Config.java`
  * `PlanningBoardDataService.java`
</Accordion>