Customize Project Templates

Like other kinds of templates you are familiar with, Project Templates save significant time when creating projects that are fundamentally the same or very similar. A template makes sense whenever it is beneficial to have some predefined configurations and/or content that can be reused for multiple new projects. For example, you might create a Project Template to be used for all new projects created for a specific team in which all project users and user roles are already defined in the template. Or you might create projects that already contain base requirements provided by the Project Template.

A Project Template can contain any project-scope settings and content that a project can contain. Here are some common things it can make sense to include:

• Project repository structure — trunk/branches/tags for example.

• Project-scope configuration — custom fields, categories, enumerations — especially Work Item types and workflows, notifications scheme, default Documents and Pages, and even project user roles if specific users should be assigned the same roles in all instantiated projects.

• Any general resources or their templates — additional empty folders, outlines and/or structures of Documents or Pages. It is also possible to include Work Items in a Project Template, but that requires some special configuration to prevent conflicting IDs, because a template may be used to create multiple projects. See Replace Work Item Prefix, later in this topic.

Users who do not have administrator permissions can work on developing custom Project Templates using the approaches outlined in this topic, but only administrators can upload or download templates to and from the Polarion portal. The Administration interface provides access to all the Project Templates available with the license or licenses on your Polarion portal. The administration page appears only in the Repository scope. On the administration page you can:

• View Project Templates. The page includes any custom Project Templates that have been developed and uploaded. You can select All to see all available templates, or filter the view to show only Polarion Templates, or only Custom Templates.

• View the properties of any Project Template. Properties include the ID, name, description, and Polarion license required for use.

• Create a duplicate of any Project Template listed on the page.

• Download a selected Project Template to your local drive for customization.

• Upload a customized Project Template to the portal. A template with the same name as an existing template overwrites it. A template with a new name appears as a new template in Custom Templates even if it was originally an existing template that was downloaded.

  Caution:

  If you overwrite an existing Project Template, the original version is no longer accessible in the portal. It still exists in earlier revisions in the integrated repository, but requires a Subversion administrator using an external client to gain access to it. Best practice is to keep all stock Project Templates and customize only copies.

• Find Project Template extensions. Access a hyperlink that leads to the Project Templates page of the Polarion Extensions portal.

The procedure to access Project Templates in Administration is as follows:

1. Log on to the portal with global administrator permissions and enter the Administration interface using the Administration link in the tool view of Navigation.

2. If you are in a project after logging on, open the Repository.

3. In Navigation, select Project Templates.

You can view the properties of any template in the Project Templates administration page. This is useful if you are planning to create custom templates because each Project Template in the system must have a unique ID. By viewing properties of existing Project Templates, you can ensure that you do not give any custom Project Template a duplicate ID.

To view Project Template properties:

1. Access the Project Templates page in Administration.

2. On the Project Templates administration page, select a Project Template .

3. In the page toolbar, click the Properties button. The Project Template Properties dialog box appears, which displays the template ID, name, description, and compatible product licenses.

You can easily create a duplicate of any existing Project Template. This is a recommended approach to creating a customized version of an existing template. You create a duplicate template, then download and customize it.

To duplicate a Project Template:

1. Access the Project Templates page in Administration.

2. On the Project Templates administration page, select the Project Template you want to duplicate. After selecting, review the properties and note the template's ID.

3. On the page toolbar, click the Duplicate button. The Duplicate Project Template dialog box appears.

4. Enter a value in the ID field. Note that the ID must be unique among all Project Template IDs. If you enter a value that already exists as the ID for another Project Template, the duplication operation fails with an error message.

5. Enter a value in the Name field and click OK. A new icon for the new duplicate appears in the Custom Templates section of the page.

Immediately after duplication, the duplicate Project Template appears in the New Project dialog box can be used by any administrator to instantiate new projects. Of course, it provides exactly the same configuration and content as the original template until it has been customized and committed back to the repository. Assuming you are creating a duplicate Project Template preparatory to customizing it, you should make sure all administrators know not to use the duplicate Project Template until customization is complete.

To create a customized version of a Project Template, you need to download it to your local computer, modify it, and upload the modified version to the portal. You can download any template on the Project Templates administration page.

To download a Project Template for customization:

1. Access the Project Templates page in Administration.

2. On the Project Templates administration page, select the Project Template you want to download. After selecting, it's a good idea to review the properties and note the template's ID.

3. On the page toolbar, click the Download button. The file save dialog of your operating system appears.

4. Save the Project Template to any location on your local system. The template is downloaded as a Zip archive.

You can use any of the Project Templates shipped with your Polarion product, or available on the Polarion Extensions portal as the basis for custom Project Templates.

When you decide which of your existing Project Templates you want as the basis for a custom Project Template, you have two options:

• Download an existing Project Template, customize the downloaded template, and upload the modified template overwriting the original.

• Create a duplicate of a Project Template, download and customize the duplicate, and upload the modified duplicate.

After downloading a Project Template, you can perform customizations by editing various files on your local system. You will need a text editor application at a minimum. A editor for HTML and XML is recommended.

Each Project Template may contain a file named template.properties in its root. Use of this file is not required, but is recommended. The file has a standard Java properties file format. For a list of the properties that can be set, see Project Template Properties.

You can potentially use some existing project as the basis for a Project Template. If you do that the project should not be referencing any specific revisions - baselines, frozen Work Items or Test Runs, for example, unless you are sure that the template will always be used with the same repository. Such references can cause problems if the template is used on a different repository. Best practice is to avoid creating a template from a project that contains specific revision references.

There are two basic approaches to template customization:

1. Local modification of an existing template. Download an existing Project Template, locally edit downloaded configuration and content files using a text editor, and then upload a modified archive of the template to the Polarion portal. This option is for more advanced users who are experienced with Project Template structure and customization.

2. Develop a template project online. Customize an existing project online in the portal — a Sandbox project created for the purpose, for example. Then save a local copy of changed and added files, and upload an archive of these to the Project Template on the portal that you want to customize. This option is probably better if you are just getting started with customizing Project Templates.

With this approach, you download an existing Project Template, modify existing component files locally, create any new component files needed for the template, and upload a new version of the template to your Polarion portal using the same file name to overwrite the existing template, or a new file name to create a new custom template.

1. Download a copy of the Project Template you want to customize from the Project Templates administration page and unpack the archive.

2. Edit the XML files in the local copy of the Project Template, creating new XML files — for new Documents, Pages, etc. as needed.

3. Edit the template.properties file, specifying a unique ID for the customized template, and an appropriate name and description.

4. Create a Zip archive containing all the files belonging to the template, including any files which you did not change. If you downloaded a template provided with Polarion, or a duplicate template created for the purpose of customizing it, and you want your changed version to overwrite the original version on the server, then name the Zip archive with the same file name as the archive of the template you downloaded.

   If you want to preserve the original version of a Project Template you downloaded from the server and have your customizations appear as a new template, give the zip archive a file name different from that of the downloaded template.

5. Upload the Zip archive to the portal using the Upload button on the Project Templates administration page.

With this approach you develop a sandbox project online in your Polarion portal so that it has all the features and content you need for similar projects, and then create a Project Template from your template project.

1. In the Polarion portal, instantiate a sandbox project based on the Project Template you want to customize.

2. Then proceed to customize that project in the portal, modifying configurations and creating Documents, Pages, etc. as needed.

3. Use the Repository Browser to save the project folders containing modified configuration and content files to some location on your local system. Generally, the folders involved include: .polarion, _wiki, modules. You may include the template.properties file as well.

4. Create a Zip archive of the downloaded folders and files. Include the template.properties file, and give the archive a file name the same as the template name. The template.properties file and all other template files and folders must be placed in a folder the name of which is same as the template ID.

5. Upload the Zip archive containing the modified template files to the portal using the Upload button on the Project Templates administration page.

There may be cases where you want your custom Project Template to provide some predefined Work Items in the projects instantiated from it. If so, it is easier if you develop your template as a project in Polarion, and create a Project Template from that, as previously described. When you create your template development project in Polarion, you specify a prefix for new Work Items. For example, you might specify MYTMPL, in which case new Work Items in your template project will have IDs like MYTMPL-100, MYTMPL-101, and so on.

When your Project Template is finished and deployed, and when users create a project based on your template, they will be able to specify a prefix for new Work Items in their new project. For example, suppose the project creator specifies FSPECS as the Work Item prefix for a project based on your Project Template. New Work Items created by project users will have IDs like FSPECS-100, but any predefined Work Items provided by your Project Template will not have this prefix. Rather, they will retain the original MYTMPL prefix. You need to make sure to replace your Work Item prefix with the user-specified prefix in user-created projects. Because not all Project Templates need to provide default Work Items, this prefix replacement is not enabled by default in custom templates.

process=.polarion/tracker/fields/workitem-type-enum.xml

You can optionally create and configure a file named access.template which, when created in the root folder of a Project Template, controls low-level access permissions for new projects instantiated on the Project Template. Rather than being copied into the instantiated project, the file content is inserted into the Subversion access file, assuming one is configured and accessible, which it normally is.

The following listing provides an example of an access.template file:

[groups]
{$project_id}-project_admin = {$current_user}
{$project_id}-project_user =

[{$project_location}]
* =
@admin = rw
polarion = r
@{$project_id}-project_admin = rw
@{$project_id}-project_user = r

[{$project_location}/.polarion]
@{$project_id}-project_admin = rw
@{$project_id}-project_user = r

[{$project_location}/.polarion/tracker/workitems]
@{$project_id}-project_admin = rw              

Pay particular attention to the references to user roles such as project_admin and project_user. The role identifiers in the above example are defaults in some Project Templates delivered with Polarion products. If custom roles have been configured in your the Project Template, you should reference the identifiers of those roles when configuring the access.template file.

Be aware that if no access.template is defined in a Project Template, Polarion will add the content of the default access.templateto the access file when a new project is instantiated from the template.