Manage projects

This section describes how to manage and maintain ALM projects and templates. In this topic, the term "project" refers to both projects and template projects.

In this topic:

View and edit project details

You can view project details such as database and project directory. You can also edit some project settings, including the maximum number of users allowed to connect concurrently to the project.

Permission:

To edit project details, you should have the following permission:

• On-premises: Site admins.

• SaaS: Site admins or customer admins, or have one of the following permissions:

  • Projects > Project Details Update

  • Projects > Create Project

To view or edit the details of a project:

1. Open the Site Administration > Projects tab.

2. In the Projects list, click the project you want to view or edit.

3. Check the Details tab. For details, see Details tab.

4. Click Save to save your changes.

Back to top

Add users to a project

You can control access to a project by adding users to or removing users from the project.

Permission:

To add site users to or remove site users from a project, you should have the following permission:

• On-premises: Site admins.

• SaaS: Site admins or customer admins, or have the User Management > Update User Membership in Projects permission.

To add users to a project:

1. Open Site Administration > Projects tab.

2. In the Projects list, click the project you want to add users to.

3. In the Users tab, click Add Users.

   You can add users from the Users list or copy users from existing projects.

   Add From the Users List	To add site/customer users to the current project: From the users list, select the users you want to add to the project. You can use the search button to search users by username. Click Save.
   Copy From Another Project	To copy users from existing projects: From the Projects list, click the project whose users you want to copy. You can also use the search button to search users by username. The filtered users are highlighted in the Projects list. Select the users you want to copy, and click Save.

4. Assign groups to the project users.

   To assign groups to a project user, click the Group drop-down field, and select the user groups you want to assign to the user.

   When you copy users from other projects	These users are added with the same user group they had in the project from which they were copied. If the user group does not exist in this project, the users are added with the Viewer group privileges. If you copy a user from another project in which the user is a project administrator (TDAdmin user group), the user is automatically assigned as a project administrator in the new project.
   When you add users from the Users list	These users are added with the Viewer group privileges (read-only privileges).

To remove users from a project:

When a user is no longer working on a project, remove the user from the project to ensure project security. Removing a user from a project does not delete the user from the Users list.

To remove users from a project:

1. In the Users tab, select the users to remove.

2. Click Remove Users, and click Yes in the confirmation dialog box.

Back to top

Enable extensions for a project

Extensions provide added functionality to ALM. If you have a license for an ALM extension, you can utilize its added functionality after enabling the extension on a per project basis.

You cannot disable an extension for a project after you enable it. We recommend you enable only the extensions you need. If you enable extra extensions, it may affect performance and consume additional disk space.

Permission:

To enable extensions for a project, you should have the following permission:

• On-premises: Site admins.

• SaaS: Site admins or customer admins, or have one of the following permissions:

  • Projects > Project PC Extension Details Update

  • Projects > Project Lab Update

To enable extensions for a project:

1. Open Site Administration > Projects tab.

2. In the Projects list, click the project you want to enable extensions for, and click the Extensions tab.

   The tab lists the extensions that are already enabled for the project.

3. To enable additional extensions, click Enable Extensions.

   The Enable Extensions dialog box opens, displaying the list of extensions available for your ALM edition on the ALM server.

   Note: Extensions without licenses on the server are displayed in gray. It is possible to enable an extension for which you do not yet have a license. You can utilize the extension's added functionality later, after receiving the license.

4. Select the extensions you want to enable and click Enable.

Back to top

Link a template to projects

You link a template to projects as part of cross project customization. The template administrator uses cross project customization to apply template customization to the linked projects. You can link a template to multiple projects, however, you can link a project to only one template.

You can also link a template to a project when you create a project. For details, see Create projects.

Permission:

To link a template to a project, you should have the following permission:

• On-premises: Site admins.

• SaaS: Site admins or customer admins, or have one of the following permissions:

  • Projects > Update Template Linked Projects List

  • Projects > Create Project

To link a template to projects:

1. Open Site Administration > Projects tab.

2. In the Projects list, click the template project you wan to link to projects, and click the Linked Projects tab.

   This tab lists the projects that are already linked to the template.

3. To link more projects to this template, click Add Projects.

4. From the All Projects list, select the projects you want to link to the template, and click the right arrow .

5. Click Save.

To unlink projects from a template:

1. In the Linked Projects tab, select the projects to unlink.

2. Click Remove Projects and click Yes in the confirmation dialog box.

Back to top

Query project tables

You can query specific data that is stored in your project. You query a project by defining and running SQL queries.

Permission:

To run a query on a project, you should be site admin.

To query a project table:

1. Open Site Administration > Projects tab.

2. In the Projects list, click the project for which you want to query the tables, and click the Database tab.

3. From the project's tables list, select a table. ALM automatically runs the "SELECT *" query for this table and displays all the data for the table in the SQL query results grid.

   

4. Define a query by typing an SQL statement in the SQL pane.

5. Click Execute SQL. The data returned by the query is displayed in the SQL query results grid.

   To export the query results, click Download to CSV.

Back to top

Export a project

Exporting ALM projects enables you to take project data from an ALM server, and back it up in another location or another media device. For example, you may want to create self-contained project image files that are backed up on a USB storage device or DVD. You can send the media device to an ALM server in another location, and import the project files.

Permission:

To export a project, you should be site admin.

Before your start

Consider the following before you export a project:

Extension	If you export an ALM project that has extensions installed, all data from the project is exported, including data for the extensions. You can only import such an exported project to a server that has the relevant extensions installed.
Disk space	Ensure adequate disk space in your home directory on the ALM client machine to temporarily store the exported project file, even if you choose an alternate location for saving the file.
Import to original server	You cannot import the project onto the original server, if a project with the same PUID exists on that server.
Export during off-peak hours	It may take some time to export large projects. It is recommended you perform this operation during off-peak hours.
Restore non-Lab Management project	If the project was not part of Lab Management, when restoring access to the project: Details about test runs will not be included in the Usage Reports. Timeslot information and project settings information are lost.

To export a project:

1. Prerequisite: You can only export a project after it is deactivated.

1. Open Site Administration > Projects tab.

2. In the Projects list, select the project you want to export, click Export .

   If the project is active, you are prompted to deactivate it.

3. The project is exported to a .qcp file which is saved in your default download path.

Back to top

Remove a project

You can remove a project or a template from the Projects list. This does not delete the project from the server and you can restore the project if necessary. For details on restoring access to a project, see Restore access to a project.

Permission:

To remove a project, you should be site admin.

To remove a project from the Projects list:

1. Prerequisite: Make sure the project you want to remove is not in use.

2. Open Site Administration > Projects tab.

3. In the Projects list, select the project you want to remove, and click Remove .

4. Click Yes in the confirmation dialog box.

Back to top

Delete a project

You can delete a project from the Projects list. This deletes the contents of the project from the server and you cannot restore the project.

Permission:

To delete a project, you should have the following permission:

• On-premises: Site admins

• SaaS: Site admins or customer admins, or have the Projects > Delete Project permission.

To delete a project:

1. Prerequisite: Make sure the project you want to delete is not in use.

2. Open Site Administration > Projects tab.

3. In the Projects list, hover over the project you want to delete, and click Delete .

4. Click Yes in the confirmation dialog box.

   If there are active users connected to the project, the users are disconnected automatically.

Back to top

Deactivate or activate a project

You can deactivate or activate a project. When you deactivate a project:

• The project name is removed from the Projects box in the ALM Login window.

• The project is not deleted from the server.

• Any users currently connected to the project are forced to log out.

Permission:

To activate or deactivate a project, you should have the following permission:

• On-premises: Site admins

• SaaS: Site admins or customer admins, or have one of the following permissions:

  • Projects > Update Project Activation Status

  • Projects > Project Details Update

  • Projects > Manage Project Versioning

  • Projects > Create Project

  • Projects > Project PC Extension Details Update

  • Projects > Project Lab Update

To deactivate a project:

1. Open Site Administration > Projects tab.

2. In the Projects list, select the project you want to deactivate, and click Deactivate.

3. Click Yes in the confirmation dialog box.

To activate a project:

1. Open Site Administration > Projects tab.

2. In the Projects list, select the project you want to activate, and click Activate.

Back to top

Enable or disable version control for a project

You can enable version control for a project. For details on version control, see Version control.

You can also disable version control for a project. When you disable version control for a project, ALM no longer stores previous versions, and deletes all version history for the project. If you enable version control for the project again, previous history is not available.

Permission:

To enable or disable version control for a project, you should have the following permission:

• On-premises: Site admins

• SaaS: Site admins or customer admins, or have one of the following permissions:

  • Projects > Manage Project Versioning

  • Projects > Create Project

To enable version control for a project:

1. Open Site Administration > Projects tab.

2. In the Projects list, select the project for which you want to enable version control, and click Enable Versioning.

3. If the project is active, you are prompted to deactivate it. Click Yes in the confirmation dialog box to deactivate it.

4. In the Enable Versioning dialog box, click OK to enable version control for the project.

To disable version control for a project:

1. Open Site Administration > Projects tab.

2. In the Projects list, select the project for which you want to disable version control, and click Disable Versioning.

3. If the project is active, you are prompted to deactivate it. Click Yes in the confirmation dialog box to deactivate it.

4. In the Disable Versioning dialog box, click OK.

5. Click Yes in the confirmation dialog box.

Back to top

Restore access to a project

You can restore access to an ALM project or template project that is not in your current projects list. For example, you may want to access a project from another server. After you restore access to a project, it is added to the projects list.

Permission:

To restore access to a project, you should be site admin.

Before you restore access to a project

Consider the following before you restore access to a project.

• Make sure the project's database exists in the Servers > DB servers tab of Site Administration on your ALM server. The ALM server needs to access the project contents from the project's database.

  For details about adding DB servers, see Add database servers.

• If the project you want to restore access to is linked to a template project, restore access to the template project first. If the template project and the linked project are in different databases, make sure the template project’s database is accessible when restoring access to the linked project.

• Under the ALM user authentication mode, after you restore a project, the project users that are new to Site Administration are locked. You can manually unlock these users to activate them. For details, see Manually unlock users.

To restore access to an ALM project:

1. Navigate to the project's dbid.xml file.

   For details about the location of the dbid.xml file, see Understand project structure.

2. Open the file, update the following values, and save the file.

   DB_NAME	Update to the database schema name as it appears in the database server.
   DB_CONNSTR_FORMAT	Update to the value of the empty project created in ALM. See the note for details.
   DBSERVER_NAME	This is the name of the database server as defined in the DB Servers tab in Site Administration.
   DB_USER_PASS	Update if the encrypted pass phrase differs between the previous installation and ALM.
   PHYSICAL_DIRECTORY	Update to the new location of the project repository. End the path with a backslash (\).

3. Open Site Administration > Projects tab.
4. Click Project Restore.

5. In the Restore Project window, define the following.

   dbid.xml file location	Click Browse to select the file that includes the project you want to restore access to. After you select the file, the database type, name, server, and the directory path of the project are displayed.
   Restore Into Domain	Select the domain in which you want the restored project to be located.

6. Click Restore.

   If your database server does not have Text Search enabled, a message box opens. You can enable Text Search before or after this process completes.

   • Click Yes to continue this process. After the process completes, you can enable Text Search

   • Click No to stop this process. Enable Text Search and then restart the process.

   For details about enabling Text Search, see Configure Text Search.

7. When the restore process completes, click OK.

8. Click Close to close the Restore Project window and view the restored project in the projects list.

Back to top

Ping a project

You can ping a project to see whether or not it is accessible.

Permission:

To ping a project, you should have the following permission:

• On-premises: Site admins

• SaaS: Site admins or customer admins, or have one of the following permissions:

  • Projects > Update Project Activation Status

  • Projects > Project Details View

  • Projects > Project Details Update

  • Projects > Manage Project Versioning

  • Projects > Create Project

  • Projects > Project PC Extension Details Update

  • Projects > Project Lab Update

To ping a project:

1. Open Site Administration > Projects tab.

2. In the Projects list, select the project you want to ping, and click Ping.

   If the project is accessible, the "Ping finished successfully" message pops up.

   If the project is inaccessible, the "Connection test failed" message pops up.

Back to top

Convert projects to Unicode

Using Unicode, your projects can support multiple languages. You can run the Unicode conversion process at the individual project level, or at the domain level to convert multiple or all projects to Unicode.

Permission:

To convert a project to Unicode, you should be site admin.

Before the Unicode conversion

Understand the following before converting projects to Unicode:

Supported project types	You can only convert the following types of projects to Unicode: Projects that are of version 11.5 or later. Projects that were created on a MS SQL server. Projects that were created in ASCII.
Increase memory	Unicode increases the memory required for the database server.
Cannot convert projects with long columns	Projects with columns whose length is greater than 4000 cannot be converted to Unicode. The validation process fails and an error message is generated. To fix the problem, either reduce the column length to 4000 or add the columns to the alm_i18n_exceptions.xml exception file before converting. System-defined columns and system-defined user fields must be reduced and cannot be added to the exception file.

To convert an individual project to Unicode:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target project, and click Maintain Project > Convert Project to Unicode.

3. Click Convert to Unicode.

   If the project is still active, you are prompted to deactivate it first.

   To abort the conversion process, click Abort and click Yes in the confirmation dialog box.

   To pause the conversion process, click Pause. To continue, click Resume.

4. Wait until the repair process completes.

   To export the repair log to a text file, click Export Log.

   To clear the repair log, click Clear Log.

To convert multiple or all projects of a domain to Unicode:

1. Open Site Administration > Projects tab.

2. From the projects list, select the target domain, and click Maintain Project > Convert to Unicode in Domain.

   Convert to Unicode in Domain is only available if the domain contains projects that can be converted to Unicode.

3. Select target projects or the click checkbox in the Project Name column to select all projects.

4. Click Convert to Unicode.

   If any of the selected projects are still active, you are prompted to deactivate them first.

   To abort the conversion process, click Abort and click Yes in the confirmation dialog box.

   To pause the conversion process, click Pause. To continue, click Resume.

5. Wait until the repair process completes.

   To export the repair log to a text file, click Export Log.

   To clear the repair log, click Clear Log.

Back to top

See also:

• Create domains
• Create projects
• Create template projects
• Monitor asynchronous executions