4. Creating & Managing Projects

Project Administration

This chapter covers administrative issues related to projects: creating, activating, deactivating, etc. For topics covering working with Projects once created, consult the User Guide.

Creating a New Project

Creating new projects requires global Administrator permissions. There are 2 basic scenarios for creating a project:

  • Create a completely new project from a Project Template. This creates a new folder in the repository as the project root.

  • Mark an existing repository folder as a project. In this way you can begin managing existing sources and other content with Polarion.

Creating a New Project from a Template

Procedures for this are covered in the User Guide topic: Creating a New Project From a Template.


If you are in Administration, open the default repository, then in Navigation select Projects, and use the New Project button on the Projects page of Administration to launch the new project dialog. The rest of the process is the same as described in the User Guide.

Marking an Existing Repository Folder as a Project

If you have an existing folder structure in your Subversion repository that you want to start managing with Polarion, you can do so by specifying the root folder and telling Polarion to "mark" it as a Polarion project.

To create a new Project from an existing repository folder tree:

  1. Log into Polarion and click the Administration link in the tool view of Navigation. Recall that you must have global Administrator permissions to access the Administration interface.)

  2. In the Open Project or Project Group dialog, click Repository.

  3. In the Navigation pane, select the Projects topic. A table of currently defined Projects loads in the Content Pane.

  4. Click the Mark Project button located on the toolbar above the table of projects.

    The new project wizard appears titled Mark existing location as Project.

    Figure 4.1. Folder as New Project

    Folder as New Project

    New project specification: specify the existing folder to mark as Project

  5. The repository root URL appears beneath the Location field. In the edit box, type the repository path to the folder you want to mark as being a Project folder. Use forward slashes (/) to separate subfolders.

    Alternatively, you can click the icon next to the edit field and use the SVN Picker dialog to browse the repository and select the folder that is to be marked as the new project root folder.


    • If you're re-marking an existing project, don't change the Project ID or you'll lose its History.

    • You can't use special characters (/\©:*?"˂˃|;ˋ~'# etc.) in the Location field.

  6. After selecting an existing SVN folder as a project root, you can proceed with the rest of the wizard steps to create and configure the new project. For information on the steps see User Reference: Create New Project Dialog.

Modifying Existing Project Properties

You may sometimes need to review existing projects and make changes to a project's properties. For example, if a project is no longer active, you may want to set its status to Inactive. Or if your organization utilizes Work Records, you may need to periodically set a date for locking Work Records created in a project.

Accessing the Projects Table

In the Administration interface, you can easily access a table listing all the Projects in Polarion's Subversion repository. You can select any Project in this table to see its properties, and you can modify those properties for which modification is allowed.

To access the Projects table:

  1. Click on the Repository node of the Open Project or Project Group dialog.

  2. In the Navigation pane and click theProjects node.

Table is empty if there are no projects in the repository.

Modifying Project Details

When you select a Project in the Projects table, its details appear in read-only mode in the lower pane of the Content Pane. You can edit all detail fields except ID and SVN URL (Subversion repository URL) after clicking the Edit button in the editor pane toolbar.

Adding and Removing Projects from Polarion Management

You can have projects in your repository that are not currently managed by Polarion: projects not currently under active development, for example. Removing such projects from management by Polarion does not remove any artifacts from the repository. If you want to restore a removed project (if development resumes, for example), you can do so.

Removing a Project

To remove a Project from Polarion management:

  1. Log in to Polarion with global administrator permissions

  2. In the Open Project or Project Group dialog, select the Repository node.

    (See User Guide: Accessing Projects.)

  3. In the Navigation pane, select Projects.

    The Projects table appears in the Projects page listing all projects currently being managed with Polarion.

  4. In the Projects table, select the Project you want to stop managing with Polarion.

  5. Click the Unmark and respond affirmatively to the confirmation prompt. This will stop the project from appearing in the portal, but files remain in the repository.

    Alternatively, you can click the Delete button which will remove the project from the portal and delete the files from the repository.

Moving Projects

There may be time when you want to move the location of a project within the repository. For example, the project might be finished, and you want to archive it and keep it out of the list of projects still in progress.

Polarion provides the possibility to move projects to another location in the repository. Moving preserves the project history. There are a couple of caveats to keep in mind when moving projects for any reason:

  • The target location must not have been occupied by any other project in the past.

  • Future new projects cannot reuse the project ID of any previously existing project in the repository, even if the location has been unmarked as a project.

To move a project to a different location:

  1. Log in to Polarion with global administrator permissions

  2. In the Open Project or Project Group dialog, select the Repository node. (See User Guide: Accessing Projects.)

  3. In the Navigation pane, select Projects.

    The Projects table appears in the Projects page listing all projects currently being managed with Polarion.

  4. In the Projects table, select the Project you want to move.

  5. Click the Move. The Move existing project to new location dialog appears.

  6. In the Location field, enter the target location. You can click the icon next to the field to launch the SVN Picker dialog and use it to navigate to and select the target location where you want the project to be moved.

  7. Click Next to begin the move operation. The Moving screen appears showing a progress indicator, and a message appears when the move is finished.

Important Note

  • The settings for the project in the Subversion access file are not updated by the process. You will need to be sure to change these manually.

  • The project will be unavailable to users during the move. If the project is large, the move could take several minutes. It is advisable to alert users about the move ahead of time.

  • You are prevented from renaming a project's ID when moving it, so that its History is not lost.

  • You can't use special characters (/\©:*?"˂˃|;ˋ~'# etc.) in the Location field.

Customizing Project Templates

Projects are based on a project template which provides configuration settings and/or content targeted a some specific needs or requirements. Each Polarion product comes with one or more project templates from which administrators instantiate new projects. However, you can create additional templates using the default templates as a starting point. This section provides some necessary background and explains the basic process of creating a custom project template.


You can find more project templates on the Polarion ALM extensions portal at http://extensions.polarion.com. You can create customized project templates based on these as well.

Why Create Project Templates?

Like other kinds of templates you are familiar with, project templates help save time creating and configuring projects that are fundamentally the same. A template makes sense whenever it is beneficial to have some pre-defined 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 which are then added to in individual projects.

What's in a Project Template?

A project template can contain any content that a project can contain. Here are some common things it could make sense to include:

  • Project repository structure (for example, trunk/branches/tags)

  • Project-level configuration: custom fields, categories, enumerations including Work Item types, workflows, notifications scheme, wiki pages, Documents, even user project roles if specific users should be assigned the same roles in all instantiated projects.

  • Any general resources or their templates. For example, additional empty folders, outlines and/or structures of Documents or wiki pages, etc. It is also possible to include Work Items in a project template, but that could potentially cause problems with conflicting IDs as a template gets used for creating multiple projects.

Legacy Project Templates

Prior to version 3.3.0 of the Polarion platform, default project templates shipped with Polarion were located in /.polarion/projects/templates/ in the repository, and all subdirectories in this location were considered as individual project templates. As of version 3.3.0, Polarion project templates are part of the binary distribution as plugins. Any custom project templates you may have created in prior versions remain in the repository in the same location and users can still instantiate projects based on them. If you want to create new project templates based on these, however, it is recommended to port them to the newer template implementation.

Accessing Project Templates

The Administration interface provides access to the project template(s) available with the license(s) for your Polarion portal. The administration page is available in the repository scope only. Via the administration page you can:

  • View the Polarion project templates available on your system, and any custom project templates that have been developed and committed to the repository. You can filter the view to include all available templates, only Polarion Templates, only or Custom Templates. The Polarion Templates link lets you view the Project Templates page on Polarion's extensions portal (in a new browser instance).

  • View the properties of any project template, including the ID, name, description, and license(s) required for use.

  • Create a duplicate of any project template listed on the page (either Polarion Templates or Custom Templates).

  • Download a selected project template to your local drive for customization.

  • Upload a customized project template to the repository, making a new template available under Custom Templates.

To access Project Templates administration:

  1. Log in with administrator permissions for the repository and enter the Administration interface using the Administration link in the tool view of Navigation.

  2. Open the repository in which you want to access project templates (see User Guide: Accessing Projects).

  3. In Navigation, select Project Templates.

Viewing Template Properties

You can view the properties of any project 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. Select a project template on the Project Templates administration page.

  3. In the page toolbar, click the Properties button. The Project Template Properties dialog appears, which displays the template ID as well as other properties.

Duplicating a Project Template

You can easily create a duplicate of any existing project template. This is one approach to creating a customized version of an existing template: create a duplicate, then download and customize the duplicate.

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, check the properties and note the template's ID.

  3. On the page toolbar, click the Duplicate button. The Duplicate Project Template dialog 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 will fail 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 wizard can be used by any administrator to instantiate new projects. Of course, it will provided 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.

Downloading a Project Template

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

Creating a Custom Project Template

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.


To familiarize yourself with what each of the default templates provides in terms of configuration, Documents, Pages, etc. create a Sandbox project from each of the project templates listed in the Create New Project wizard and explore them. (You can delete these projects later on once you know about them.)

When you decide which of your existing project templates you want as the basis for a custom project template, can either:

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 Administration Reference: Project Template Properties.


If your custom project template is large, you may find that you cannot upload it due to the attachment size limit currently set in the system configuration. In such cases, your Polarion administrator can temporarily increase the limit set in the maxAttachmentSize system property.

Approaches to Template Development

There are 2 basic ways you can approach template customization:

  • Edit downloaded configuration and content files belonging to a project template using a text editor, and upload a modified archive to the portal. (This option is more for advanced users who are experienced with project template structure and customization.)

  • Customize an existing project 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.)

Customizing Local Files
  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 (e.g. for new Documents, wiki 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 "stock" template provided by 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 filename 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 filename 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.

Customizing using the Portal and SVN
  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 filename 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.

Replacing Work Item Prefix

There may be cases where you want your project template to provide some pre-created Work Items in projects based on it. In this case, you will probably 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, etc.

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 the "default" 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.

If Custom Templates are Used:

To have Polarion replace the Work Item Prefix from template-provided Work Items, add the following lines to your template.properties file: trackerPrefixToReplace=PREFIX, where PREFIX is the Work Item prefix specified in the project template's development project. For example, if your development project's Work Item prefix is "MYTEMPL", then you should specify trackerPrefixToReplace=MYTEMPL in the properties file.


These lines are added automatically in templates that ship with Polarion.

Controlling Access to Instantiated Projects

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 if one is configured and accessible (which is normally the case).

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

{$project_id}-project_admin = {$current_user}
{$project_id}-project_user =

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

@{$project_id}-project_admin = rw
@{$project_id}-project_user = r

@{$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.template to the access file when a new project is instantiated from the template.

Using External Repositories (GIT, SVN)

Polarion supports revision links with external Subversion or Git repositories in addition to the "default" Subversion repository installed and/or configured during Polarion installation. If you have existing repositories that you want to use with your Polarion installation, you will need to configure your portal or projects to work with them. You can do this in the Repositories topic of Administration in the global repository or project-specific scope.

For information and procedures, see Administrator's Guide: Configuring Repositories: Configuring External Repositories (Git, SVN).