View Source

{toc:style=disc|indent=20px|maxLevel=5}

{hidden-data}
Suggested workflow:
* Initial setup > Modify/create roles > Modify/create groups > Create users > Create project
{hidden-data}

h1. Admin Area Overview
Provided that you have sufficient permissions, you can enter YouTrack Admin area by clicking *Administration* in the top right corner of YouTrack:
!admin_link.png!
Admin area consists of the following pages:
* *Projects*. This is an overview of existing issue tracking projects, with options to [create a new project|#CreatingaNewProject] or [import an existing project|#ImportingaProjectfromJIRA] from a JIRA instance:
!tabs_projects.png|thumbnail!
* *Users*. This is a list of registered YouTrack users with filters and a link to user registration page:
!tabs_users.png|thumbnail!
See [Administering Users|#AdministeringUsers].
* *Groups*. This page lists and describes existing user groups, and provides an option to [create new groups|#CreatingaGroup]:
!tabs_usergroups.png|thumbnail!
* *Roles*. This is a list of roles configured in the current YouTrack instance, with detailed permissions associated with them:
!tabs_roles.png|thumbnail!
See [Configuring Roles|#ConfiguringRoles] and [Assigning Roles to Users|#AssigningRolestoUsers].
* *Issue Link Types*. This is a list of issue links configured in the current YouTrack instance:
!tabs_issue_link_types.png|thumbnail!
YouTrack comes with 3 predefined link types but you can configure your own types.
Link type configuration comes down to wording and whether the link is directed or not.
For directed links, you should specify two names: an inward name for the object of a link (e.g. "is duplicated by") and an outward name for the subject of a link (e.g. "duplicates").
{anchor:reference_setup}
* *Setup*. This page lets you configure license data, base URL of your YouTrack installation, enable guest account and notifications. This is the first page that is displayed after you have installed YouTrack:
!tabs_setup.png|thumbnail!
See [Initial Setup|#initial_setup] for further details.
* *Database*. This page lets you switch YouTrack database between read-write and read-only states, monitor database performance data, as well as schedule, configure, and retrieve database backups:
!tabs_database.png|thumbnail!
See [Administering Database|#AdministeringDatabase] for further details.
* *Text Index*. This page lets you configure languages to take account of during text indexing, and provides a button to suspend it:
!tabs_text_index_settings.png|thumbnail!
Suspending text indexing is useful when a massive amount of documents to index considerably impairs server performance (for example, in peak hours). Another use case is to suspend text indexing for creating a backup right after you have imported a new project.
* *System Info*. This page displays server statistics: available, allocated, and used memory, as well as the number of available processors:
!tabs_system_info.png|thumbnail!
* *Statistics*. Use this page to view usage statistics for your YouTrack installation. Currently, it only has one tab, *Browsers Usage*:
!tabs_statistics.png|thumbnail!
* *Entity Browser*. This is a simple YouTrack database viewer for troubleshooting purposes. If something goes completely wrong with your YouTrack installation, you might have to report some entity data from this page:
!tabs_entity_browser.png|thumbnail!
* *JIRA Integration*. This page incorporates JIRA integration settings:
!TSYSD:FAQ^jira_integration.png|thumbnail!
See [Importing a Project from JIRA|#ImportingaProjectfromJIRA].
* *LDAP Integration*. This page helps configure YouTrack to allow users in your company to log in using credentials stored in your directory service:
!tabs_ldap.png|thumbnail!
See [LDAP Integration|#LDAPIntegration].
* *OpenID Integration*. This page lets you enable any or all of five OpenID providers supported by YouTrack:
!tabs_openid.png|thumbnail!
See [OpenID Integration|#OpenIDIntegration].
* *TeamCity Integration*. This page helps integrate YouTrack with [JetBrains TeamCity|http://www.jetbrains.com/teamcity/] for linking issues to VCS commits and automatically filling "Fixed in build" attribute values:
!tabs_teamcity.png|thumbnail!
See [TeamCity Integration|#TeamCityIntegration] and/or [TeamCity Integration Guide|TeamCity Integration Guide].

{anchor:initial_setup}
h1. Initial Setup

When you run YouTrack for the first time, it requires you to log in. For initial setup, use the default username/password pair: *root*/*root*.

{info:title=Default credentials}For initial setup, use the default username/password pair: *root*/*root*.
{info}


Once you have logged in, the initial configuration page ({{base_URL/setUp}}) opens where you should specify your license data:
!tabs_setup.png|thumbnail!
If you're using a EAP build, you can find a valid user name and license key at the [EAP Build Installation|http://jetbrains.net/confluence/display/TSYSPUB/EAP+Build+Installation] page.
In addition, you can:
* Enter the base URL of your YouTrack installation so that links to issues in your e-mail/jabber notifications can be constructed properly.
* Enable guest account in your YouTrack installation (you can start managing guest permissions after you've logged in.)
* Enable issue status notifications via e-mail and/or Jabber.

When you've finished configuring the initial settings, click *Save* and enter your password to apply the settings. You will be redirected to the *Projects* page (see [Administering Projects|#projects]).
You can change these settings later using the [*Setup* page|#reference_setup] ({{base_URL/settings}}).

{info:title=Notes about 'root' user}Currently, the default {{root}} user account cannot be deleted. If you prefer to use another account to administer YouTrack instance, configure new admin account properly, and then [ban|#Miscellaneous] the {{root}} account. For more details about administering user accounts refer to the [corresponding section of this guide|#Administering User Access].
{info}

h1. Administering YouTrack Instance

{anchor:AdministeringDatabase}
h2. Administering Database
h4. Changing Database Location
*YouTrack* uses its own in-process database. By default, data files are saved to *$\{user.home\}/teamsysdata* directory.
To change this default location, modify {{database.location}} parameter in file *youtrack-xx.war:/WEB-INF/web.xml*:
{code:xml}
<web-app>
<display-name>YouTrack</display-name>
<servlet>
<servlet-name>MainServlet</servlet-name>
<servlet-class>jetbrains.charisma.main.ServletImpl</servlet-class>
<init-param>
<param-name>database.location</param-name>
<param-value>${user.home}/teamsysdata</param-value>
</init-param>
...
</servlet>
...
</web-app>
{code}

h4. Backing Up Database
YouTrack database controls are available by clicking *Database* in the Admin Area. Specifically, you can back up YouTrack database right away or schedule backups using cron expressions (see [cron expression syntax|http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html] for reference).
There are several things to take note of regarding YouTrack database settings and controls:
* YouTrack automatically switches database to read-only mode after you have launched database backup.
* You can't cancel database backup once it has started.
* Users aren't able to access YouTrack during database backup, so be sure to configure backup schedule wisely.
* Notifications about database backup status can only be configured for YouTrack application administrators.
* You _don't_ have to back up your database in order to upgrade to a newer YouTrack build or version - YouTrack will find your database automatically after upgrade.

{anchor:projects}
h1. Administering Projects

YouTrack allows you to [create new projects|#projects_new] or [import existing projects from JIRA|#projects_jira].

{anchor:projects_new}
h2. Creating a New Project
*To create a new empty project:*
# In the *Projects* page ({{base_URL/projects}}), click *Create new project*.
# Enter name, ID, and description for the new project, and select a user as the project lead.
bq. As a general rule, before creating projects on top of an empty YouTrack installation, it is recommended that you configure [roles|#ConfiguringRoles], [groups|#AssigningRolestoaGroup] and [users|#AdministeringUsers] (in this particular order).
# Click *Create*. The project properties page will open at the *Assignees* tab. You can now proceed with [configuring the project|#projects_configuring].

{anchor:projects_jira}
h2. Importing a Project from JIRA
YouTrack is able to import existing projects from JIRA 3.8-3.13.4. A project is imported along with user accounts that have access to it, and (optionally) roles, groups, and group memberships. See [JIRA Integration|#JIRAIntegration] for details on JIRA Integration features.
*To import an existing project from JIRA:*
# In the *Projects* page ({{base_URL/projects}}), click *Import existing project from Jira*.
# In the *Jira Integration* page, use provided links to download a plug-in for JIRA that enables importing issues to YouTrack. Get one of two available YouTrack plug-ins depending on your JIRA version:
** YouTrack plug-in for JIRA 3.8-3.9.3 (available at {{base_URL/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.8.1-3.jar}})
** YouTrack plug-in for JIRA 3.10-3.13.4 (available at {{base_URL/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.10-3.jar}})
# Install the appropriate YouTrack plug-in in your JIRA instance by following guidelines for "Version 1" plug-ins in [Managing JIRA Plugins|http://confluence.atlassian.com/display/JIRA/Managing+JIRA%27s+Plugins].
# Make sure that [remote API is enabled in JIRA|http://confluence.atlassian.com/display/JIRA/Enabling+the+RPC+plugin] and the YouTrack plug-in has appeared in the list of JIRA plug-ins as "Charisma JIRA plugin".
# Getting back to YouTrack, click *Enable Jira Integration*.
# Specify JIRA base URL, your JIRA credentials (note that you must have administrative privileges in order to import projects), a project to import, and choose issue types within the selected project:
!TSYSD:FAQ^jira_integration.png|thumbnail!
# To import groups, roles, and group memberships, select *Import Security Settings*.
# Click *Import Project*.
bq. When you re-import a previously imported project, YouTrack only processes issues that have been added or changed since.

{anchor:projects_configuring}
h2. Configuring a Project
*To configure a project:*
# In the *Projects* page, click the name of a project that you want to manage.
# In the project-specific page ({{base_URL/editProject/project_ID}}), use the following five tabs to modify various project settings:
** *Main*. General project settings that are usually configured on [project creation|#projects_new], including *Name*, *ID*, *Project lead*, and *Description*.
** *Assignees*. Users that can act as assignees within the project.
You can add assignees as individual users (click *Add individual assignee*), groups (click *Add/remove groups*), or both.
The *Full assignees list* table shows all users who act as assignees in the current project by virtue of group membership or per-user configuration. The *Assigned by* column lets you know how exactly a particular user has become an assignee in the current project:
!project_assignees.png|thumbnail!
** *Subsystems*. Using this tab, you can:
*** Add new subsystems to the project.
*** Choose default assignees for different subsystems (any new unassigned issues within a subsystem are automatically assigned to its default assignee.)
*** Set a default subsystem (the subsystem that YouTrack suggests by default when you create new issues in the project.)
bq. Subsystems are generally used to differentiate between large, consistent project components (such as "Notifications" in YouTrack's own issue tracking project.) However, in many cases [tags|Contextual Help. Tags] are just enough to group a set of similar issues. Unlike subsystems, tags can be created by users themselves (provided they have sufficient permissions).
** *Versions*. Using this tab, you can create project versions, set release dates for them, mark them as released (you can reference released versions in "affected version" attribute) or archived (you can search for issues related to archived versions but you can't reference archived versions in issue attributes):
!projects_versions.png|thumbnail!
** *Builds*. Using this tab, you can set build names/numbers and build assembly dates. If [TeamCity integration|#TeamCityIntegration] is configured, the list of successfully assembled builds is automatically generated in this tab:
!projects_builds.png|thumbnail!
# Click *Save* to save project settings.

h1. Administering User Access
We suggest that you configure user access in the following order:
# [Create new roles or configure predefined roles|#ConfiguringRoles].
# [Create new groups or configure predefined groups|#CreatingaGroup].
# [Assign roles to groups on a per-project basis|#AssigningRolestoaGroup].
# [Configure group membership for YouTrack users|#AdministeringUsers].

h2. Configuring Roles
A role in YouTrack is a set of permissions. Roles are applied to groups _on a per-project basis_ (within specified projects).
YouTrack is bundled with four predefined roles: _Admin_, _Developer_, _Reporter_, and _Observer_.

The following table provides an overview of the predefined roles:
||Predefined role||Permissions||
|Admin|All permissions included|
|Developer|View existing issues; create, modify, assign, link, and delete issues \\
Add attachments to issues and delete them \\
Create comments \\
View and modify own user profile \\
Create, modify, and delete tags or saved searches\\
Mark issues as watched and view lists of other users who are watching issues \\
Vote for issues and view lists of other users who have voted for issues|
|Reporter|Report new and view existing issues \\
Read public comments; create, modify and delete own comments \\
View and modify own user profile \\
Create, modify, and delete tags or saved searches|
|Observer| View public issues \\
Read public comments|

You can edit these predefined roles and/or create new roles.
The following procedure describes creating a new role. To edit an existing role, click its entry in the *Roles* page.

*To create a new role:*
# In the Admin Area, click *Roles*.
# Click *Create new role*.
# In the role editing page, enter a name and (optionally) description for the new role.
!roles__new_role.png|thumbnail!
# Assign permissions listed and described in the role editing page.
# Click *Create*.

Once you have created and/or configured necessary roles, [create or configure user groups|#CreatingaGroup], and [assign roles|#AssigningRolestoaGroup] to them on a per-project basis.

{hidden-data}
по умолчанию в ютреке только две группы: All users и New users?
[14:46:27] Vadim Gurov says: да
[14:53:07] Jura Gorohovsky says: предполагается, что настраивать полномочия для новых пользователей нужно в New users, а All users оставить с богом без ролей сугубо для статистики и удобства фильтрации? или как?
[14:54:13] Vadim Gurov says: пользователя же можно выкинуть потом из New Users и тогда он будет обладать правами только группы All Users
[14:54:54] Vadim Gurov says: поэтому стратегия такая: All Users - что может видеть гость
New Users - что может видеть зарегестрированный юзер
[14:56:11] Vadim Gurov says: я, например, админю так: All Users - только чтение багов и коммоентов в "открытых" (c открытой инфой) проектах
[14:56:42] Vadim Gurov says: New Users - сабит новых багов и комментов в открытые проекты
[14:56:58] Vadim Gurov says: далее есть группа jetbrains-users - те видят и меняют все
[14:57:34] Vadim Gurov says: еще есть роли - Observer, Reporter, Developer - они навешиваются соответственно на All USers, New USers, jetbrains-users
[14:58:27] Jura Gorohovsky says: т.е. предустановленных роли четыре: Admin, Developer, Reporter, Observer?
[14:59:07] Jura Gorohovsky says: в этом свете предлагаю переименовать группу "New users" в "All registered users"
[15:19:02] Vadim Gurov says: если пользователя выкинут из группы All registerd, он от этого не перестанет быть таковым
так что название не полно оражает суть
New USers как раз нормально, ты оттуда можешь юзеров перекладывать в другие группы, более привелегированные
но нового юзера ты всегда гарантированно там найдешь
{hidden-data}


h2. Configuring Groups
h3. Creating a Group
The following procedure describes creating a new group. To edit an existing group, click its entry in the *Groups* page.
*To create a new group:*
# In the Admin Area, click *Groups*.
# Click *Create new group*.
# In the group editing page, enter a name and (optionally) description for the new group.
!groups__new_group.png|thumbnail!
# Select *Auto Join* to automatically add any new registered users to this group.
# Click *Create*.

Once you have created necessary groups, start [assigning roles|#AssigningRolestoaGroup] to them.

h3. Assigning Roles to a Group
*To assign a role to a group:*
# In the Admin Area, click *Groups*.
# In the *Name* column, click the name of a group that you want to assign roles to.
# In the group editing page, click *Roles*.
# In the *Roles* tab, click *Assign role*. The *Assign Role* dialog box opens.
# In the *Role* drop-down list, choose a role to assign.
# In the *Projects* combo box, select one or several projects to apply the selected role:
!TSYSD:FAQ^new_users_reporter.png|thumbnail!
# Click *OK*.

When you have assigned roles to a group, the *Permissions View* tab in group properties appears. It shows all permissions assigned to the current group via different roles:
!groups__permissions.png|thumbnail!

Once you have prepared user groups with properly assigned roles, start [adding users|#AdministeringUsers] into your groups.

h2. Administering Users

h3. Creating User Accounts
In YouTrack, users are expected to create their user accounts themselves.
If for some reason you need to create accounts on behalf of users, you can do it using the regular user registration page at {{base_URL/registerUserForm}}. For your convenience, there's a link to this page just above the list of users in the Admin Area:
!tabs_users.png|thumbnail!
Whichever user registration procedure you choose, you need to create and/or configure a group that every new user will join, assigning it adequate permissions. See [Assigning Roles to a Group|#AssigningRolestoaGroup] for details.

h3. Importing User Accounts from JIRA
User accounts are imported from JIRA along with projects. See [JIRA Integration|#JIRAIntegration] for details.

h3. Adding Users to Groups
You can add a user to a group from either the *Groups* page or the *Users* page.
*To add a user to a group from the Groups page:*
# In the Admin Area, click *Groups*.
# Choose a group from the list of groups, and click *Add User*.
# In the *Select User* dialog box, select a user:
!user_to_group__Groups.png|thumbnail!
# Click *OK*.

*To add a user to a group from the Users page:*
# In the Admin Area, click *Users*.
# Find a user entry using filters in the *Filter* area.
# In the list of found users, locate a user that you want to add to a group.
# Click *Groups* for the user entry in the list of found users. This opens the administrative part of the user profile at the *User Groups* tab.
# Click *Add to groups / Remove from groups*.
# In the *Select Groups* dialog box, select one or several groups to add the user to:
!user_to_group__Users.png|thumbnail!
# Click *OK*.

Once you have added the user to one or several groups, click *Permissions View* for the list of specific permissions that the user is granted via group memberships or [own roles|#AssigningRolestoUsers].

h3. Excluding Users from Groups
Excluding a user from a group should be done via user properties as opposed to group properties.
*To exclude a user from a group:*
# In the Admin Area, click *Users*.
# Find a user entry using filters in the *Filter* area.
# In the list of found users, locate a user that you want to exclude from a group.
# Click *Groups* for the user entry in the list of found users.
# In the *User Groups* tab, click *Unassign* for a group that you want to exclude the user from.

h3. Assigning Roles to Users
In addition to granting permissions via groups, you can assign roles to users individually.
*To assign a role to a user:*
# In the Admin Area, click *Users*.
# Find a user entry using filters in the *Filter* area.
# In the list of found users, locate a user that you want to assign a role to.
# Click *Roles* for the user entry in the list of found users. This opens the administrative part of the user profile at the *User Own Roles* tab.
# Click *Assign role*.
# In the *Assign Role* dialog box, choose a role to assign to the user:
!role_to_user.png|thumbnail!
# Select one or several projects where you want to apply the role.
# Click *OK*.

Open the *Permissions View* tab for the list of specific permissions that the user is granted via his/her own roles or [group memberships|#AddingUserstoGroups].


h3. Miscellaneous
You can delete, merge, or ban user accounts, all from the list of users in the *Users* page.

*To merge two user accounts:*
# In the *Users* page, locate a user account that you want to merge with another user account.
# Click *Merge* for the user entry in the list of found users.
# In the *Select User* dialog box, select a user account to merge with:
!merge_users.png|thumbnail!
Note that if you're merging a less privileged user account with a more privileged user account, the resulting user account gets the more advanced permissions.
# Click *OK*.

As a result of merging, any roles, group memberships, and assigned issues are transferred to the surviving user account.

*To ban a user account:*
# In the *Users* page, locate a user account that you want to ban.
# Click *Ban* for the user entry in the list of found users. The user account is banned immediately.

You can unban the user account at any time by clicking *Unban* in the list of users.

*To delete a user account:*
# In the *Users* page, locate a user account that you want to delete.
# Click *Delete* for the user entry in the list of found users.
# Click *OK* in the confirmation dialog box.

h1. Integrating YouTrack with External Tools

h2. TeamCity Integration
You can integrate YouTrack with your [JetBrains TeamCity|http://www.jetbrains.com/teamcity/] 5.0+ installation:
!tabs_teamcity.png|thumbnail!
TeamCity integration brings two advantages:
# TeamCity adds links from issue IDs referenced in VCS commits to actual issues in YouTrack, letting you navigate between commits and issues, and view associated changes from any issue.
# TeamCity automatically puts correct build numbers to "fixed in build" attributes of your issues after these builds have been assembled.

For more information and specific TeamCity integration guidelines, see [TeamCity Integration Guide].

h2. JIRA Integration
Integrating YouTrack with JIRA lets you execute three tasks:
* Import existing projects from JIRA, along with roles, users, groups, and group memberships.
* Update previously imported projects to account for changes made in JIRA (for example, new issues and comments that have appeared in the JIRA project since last import to YouTrack.)
* Enable users to log into YouTrack using their JIRA credentials.

For guidelines on importing projects from JIRA, see [Importing Project from JIRA|#ImportingaProjectfromJIRA].
Updating previously imported projects is basically done the same way that you import JIRA projects for the first time.
Users are able to log in with their JIRA credentials as soon as you have completed importing a project from JIRA. That's because, provided that you have selected *Import security settings* during import, YouTrack also imports all groups and roles applicable for the project being imported.

{hidden-data}
What is "Import security settings" in JIRA Integration | Import Project? Is it related to importing or reimporting groups and roles?
{hidden-data}



h2. LDAP Integration
LDAP integration lets you use user credentials stored in your directory service to log into YouTrack:
!tabs_ldap.png|thumbnail!
*To enable LDAP integration:*
# In the *LDAP Integration* tab, click *Enable LDAP Integration*.
# Enter the URL of your LDAP server.
# To make sure that the connection with your LDAP server works:
## Click *Test connection*.
## In the *Test LDAP Login* dialog box, enter a pair of user credentials stored in your directory service:
*** {{domain\username}} in the *Login* field.
*** {{password}} in the *Password* field.
## Click *Test Login*.
## If an error message if displayed, check your user credentials and/or server URL.
## Click *Done* to close the *Test LDAP Login* dialog box.

h2. OpenID Integration
YouTrack lets you enable authentication through any or all of five supported OpenID providers: Google, Yahoo, America Online, LiveJournal, and BlogSpot.
*To enable OpenID authentication:*
# In the Admin Area, click *OpenID Integration*.
# In the *OpenID Integration* page, select *Enable OpenID Integration*.
# Select OpenID providers that you want to enable:
!tabs_openid.png|thumbnail!

That's all! From now on, your users are able to log in with their OpenID credentials from {{base_URL/loginForm}}:
!openid__login_page.png|thumbnail!

h3. Configuring Additional OpenID Providers
YouTrack supports four OpenID providers out of the box but you can configure additional providers.
However, any provider that you add must support AX (attribute exchange) fetch requests and return the following attributes:
* {{http://schema.openid.net/contact/email}}
* {{http://axschema.org/namePerson/first}}
* {{http://axschema.org/namePerson/last}}

*To configure an additional OpenID provider*:
# Add a new entry to the list of {{bean}} elements in {{\[YouTrack classpath\]\jetbrains\charisma\openid\persistence\OpenIdProvidersContainer.xml}}.
# In the added {{bean}} element, add four properties:
** *{{id}}*: Unique integer identifier of your OpenID provider. Default providers are assigned IDs from 0 to 3.
** *{{v2}}*: Boolean value indicating whether your provider supports OpenID 2.0: assign "true" if it does support OpenID 2.0, otherwise "false".
** *{{iconClassPathUri}}*: Path to OpenID provider logo within YouTrack classpath ({{\webapps\youtrack\WEB-INF\classes\}} in Apache Tomcat.) Don't forget to actually add a logo image in addition to referencing it in bean properties. Use 48*48 image files for OpenID providers supporting OpenID 2.0, and 22*22 files for other providers.
** *{{providerUri}}*: OpenID provider service URL.

The following listing shows how one of default OpenID providers is configured in {{OpenIdProvidersContainer.xml}}:

{code:xml}
<beans>
<bean id="openIdProvidersContainer" class="jetbrains.charisma.openid.persistence.OpenIdProvidersContainer">
<property name="providers">
<list>
<bean class="jetbrains.charisma.openid.persistence.OpenIdProvider">
<property name="id">
<!-- Integer OpenID provider ID -->
<value>0</value>
</property>
<property name="v2">
<!-- "true" if provider supports OpenID 2.0, otherwise "false" -->
<value>true</value>
</property>
<property name="iconClassPathUri">
<!-- Path to provider logo within YouTrack classpath -->
<value>smartui/img/loginGoogle.gif</value>
</property>
<property name="providerUri">
<!-- OpenID provider service URL -->
<value>https://www.google.com/accounts/o8/id</value>
</property>
</list>
</property>
</bean>
</beans>
{code}