Custom Project Templates
You can use any project in YouTrack as a custom template for new projects. This helps you define one or more basic configurations for projects in addition to the templates that are predefined in YouTrack. When marked as a custom project template, the project is added to the list of available project types on the Create Project page.
Creating a Custom Project Template
If your organization frequently creates projects for similar types of activity, you can save a lot of time and effort by creating a custom project template. It can also help you define a standardized set of settings, fields, and workflows to be applied to all new projects in the system.
Before you mark a project as a custom project template, review the settings that are described on this page to make sure you understand how the settings for the current project are applied to new projects.
Consider editing the name and description of any project that you want to use as a custom template. These values help other users know which template to choose on the Create Project page.
Make sure the project uses all the custom fields that you want to use in multiple projects and that these fields store the desired values.
Make sure the workflows that are attached to the project do not depend on the current project to function properly. Detach any workflows that rely on references to a specific project.
To mark a project as a custom project template:
Click Projects in the main navigation menu to open the Projects list.
From the
Administration menu of the project that you want to use as a project template, select General Info.
Enable the Custom project template option.
Click the Apply changes button.
The current project is marked as a custom project template.
A template badge is added to the header of the Edit Project page.
The project is added as a Project Type on the Create Project page.
Any project that is created using the custom project template uses the settings that are stored in the source project at the time the new project is created. Modifications to the project that you use as a custom template are not replicated to projects that have already been created from the template. Changes to the configuration of the source project are only applied to projects that are created from the template after the changes are applied.
To create a project from a custom project template, follow the same steps that you would use to create a project from a predefined project template. For instructions, see Create a Project.
Project Settings
The following table describes how each of the settings in the project that is used as a custom template is applied to new projects when the project template is based on a standard project for issue tracking:
Settings | Description |
|---|---|
General | Most of the general settings from the custom project template are copied to the new project. Values for the following settings are defined when you create the new project:
|
Access | All the roles that are assigned directly to users and groups in the custom project template are granted to the same set of users and groups in the new project. An exception is made for the Project Admin role, which is assigned to the user who creates the new project. |
Team | All the users and groups who are members of the team in the custom project template are added to the project team in the new project. The user who creates the project is added to the team as the project owner. |
Fields | All the custom fields that are available in the custom project template are added to the new project. The sets of values that are available in each of these fields are copied to the new project as well. If the user who creates the project is not included in the set of values for the Assignee field, this user is added to the set in the new project. As with the predefined Scrum and Kanban templates, the settings that auto-attach custom fields to new projects are ignored. |
VCS | All the VCS integrations that link the project that is used as a custom template to a repository in a version control system are copied to the new project. The VCS integrations are disabled in the new project. |
Notifications | The From and Reply-to addresses and any notification templates that have been customized in the custom project template are copied to the new project. |
Build Server Integration | All the build server integrations that map the project that is used as a custom template to a build in a version control system are copied to the new project. The mappings are disabled in the new project. This gives you a chance to re-use most of the settings from the original project without adding new mappings. You can edit the mapping to point to a different build on the build server and enable the integration. |
Time Tracking | If time tracking is enabled in the project that is used as a custom template, the feature is enabled in the new project as well. The fields that are set as the Estimate field and Time spent field are set in the new project. All the work item types that are used in the custom project template are copied to the new project. |
Workflow | Only the workflows that are attached to the project that is used as a custom template are attached to the new project. The global settings that auto-attach workflows to new projects are ignored. |
The following table describes how each of the settings in the project that is used as a custom template is applied to new projects when the project template is based on a helpdesk project:
Settings | Description |
|---|---|
General | Most of the general settings from the custom project template are copied to the new project. Values for the following settings are defined when you create the new project:
|
Access | All the roles that are assigned directly to users and groups in the custom project template are granted to the same set of users and groups in the new project. An exception is made for the Project Admin role, which is assigned to the user who creates the new project. |
Team | All the users and groups who are members of the team in the custom project template are added to the project team in the new project. The user who creates the project is added to the team as the project owner. |
Authorized Reporters | If the custom project template is configured for restricted reporter access, new projects created using the template are restricted as well. Any reports who have been added to the custom project template are added to the list of reporters for all new projects created using the template. |
Fields | All the custom fields that are available in the custom project template are added to the new project. The sets of values that are available in each of these fields are copied to the new project as well. If the user who creates the project is not included in the set of values for the Assignee field, this user is added to the set in the new project. As with the predefined Scrum and Kanban templates, the settings that auto-attach custom fields to new projects are ignored. |
Notifications | The From and Reply-to addresses and any notification templates that have been customized in the custom project template are copied to the new project. |
Build Server Integration | All the build server integrations that map the project that is used as a custom template to a build in a version control system are copied to the new project. The mappings are disabled in the new project. This gives you a chance to re-use most of the settings from the original project without adding new mappings. You can edit the mapping to point to a different build on the build server and enable the integration. |
Time Tracking | If time tracking is enabled in the project that is used as a custom template, the feature is enabled in the new project as well. The fields that are set as the Estimate field and Time spent field are set in the new project. All the work item types that are used in the custom project template are copied to the new project. |
SLA Policies | Any SLA policies that are created in the custom project template are copied to the new project. |
Workflow | Only the workflows that are attached to the project that is used as a custom template are attached to the new project. The global settings that auto-attach workflows to new projects are ignored. |
Email Channels, Mailbox Integrations, and Agile Boards
In addition to the project settings, several configurations that are associated with the project that is used as a custom template are included when you use this template to create a new project. This can include configurations for agile boards and mailbox integrations. The following table describes the logic for generating these objects when a custom template is applied to a new project:
Configuration | Description |
|---|---|
Agile Boards | Agile boards are added to the custom project template and automatically generated for new projects when the following conditions are met:
The configuration for the new board is copied from the board that manages issues in the template project, with the following exceptions:
|
Email Channels | Email channels that have been configured in the project that is used as a custom template are copied to the new helpdesk project in a deactivated state. This gives you a chance to re-use most of the settings from the original channel without starting from scratch. You can update the settings in the new project to retrieve messages from a unique inbox and enable the channel. For more information, see Email. |
Mailbox Integrations | In standard projects for issue tracking, the mailbox rules that reference the project that is used as a custom template are copied to the new project. The mailbox rules are disabled in the new project. This gives your administrator a chance to re-use most of the settings from the original rule without adding new mailbox rules. A user who has access to the Mailbox Integrations page can simply edit the mailbox rule to fetch messages from a unique inbox and enable the integration. For more information, see Define Mailbox Rules. |
Hub Projects | If your YouTrack Server installation is integrated with an external Hub service, a Hub project is created as a container for the new YouTrack project. The new YouTrack project is added to the Hub project as a resource. All the settings that are normally inherited from the Hub project, like the project team and access scheme, are copied from the new YouTrack project to the Hub project. |
Items Excluded from the Custom Project Template
The custom template doesn't create copies of all the objects and integration settings that reference the project that is used as a custom template. The items that are listed in the following table are not copied to new projects:
Item | Description |
|---|---|
Issues | Issues that belong to the project that is used as a custom template are not copied to the new project. |
Articles | Articles that belong to the project that is used as a custom template are not copied to the new project. |
Reports | Reports that show data for issues in the project that is used as a custom template are not cloned. |
Zendesk Integrations | Settings that let you share Zendesk tickets with issues in YouTrack cannot be copied to the new project. The invitation to share tickets with a third-party system must be initiated in the Zendesk instance. To learn how to set up a Zendesk integration in the new project, see Zendesk Integration. |
Online Forms | The online forms that are used to submit support requests in helpdesk projects are not copied to new projects. This ensures that incoming support requests are not mistakenly re-routed to the wrong helpdesk. To learn how to set up an online form in a new helpdesk project, see Online Forms. |
Deleting Custom Project Templates
Over time, your organization's needs or workflows may change, rendering some project templates obsolete or redundant. Deleting these unused templates can help declutter the system and make it easier to manage.
Deleting a project template only removes the project as a tool for creating new projects. Projects that were creating using the deleted template are unaffected by this action and are retained in the system.
To delete a custom template:
Click Projects in the main navigation menu to open the Projects list.
Scroll down to the Project Templates section of the page, then click the name of the template you want to remove from the system.
The selected project opens to the Edit Project page.
Click the Delete project button at the top of the page.
A confirmation dialog opens.
Enter the name of the project in the input field, then click the Delete project button.
The project template is deleted from the system and is removed from the list of project types on the Create Project page.
Projects that were created using the project template are unaffected.