name: available pages key: ytd3 youtrack energy...

Document generated by Confluence on Feb 21, 2011 14:38 Page 1

Space DetailsKey: YTD3

Name: YouTrack Energy Documentation

Description: Documentation space for YouTrack Energy

Creator (Creation Date): admin (Sep 10, 2008)

Last Modifier (Mod. Date): ivrina (Aug 17, 2010)

Available Pages• YouTrack Energy Documentation

• Keyboard Shortcuts

• Installation and Upgrade• YouTrack Supported Environments

• YouTrack on Linux• Linux. YouTrack JAR as a Service

• Linux. YouTrack JAR as a Service. Old Method

• Linux. JAR in Apache Web Server

• Linux. JAR in Nginx Web Server

• Linux. WAR within Servlet Container and Apache Web Server

• Linux. WAR within Servlet Container and Nginx Web Server

• YouTrack on Windows• Windows. Installing and Running YouTrack as a Service

• Windows. YouTrack JAR and Apache Web Server

• Windows. WAR and Tomcat Servlet Container

• Windows. WAR within Servlet Container and Apache Web Server

• Administrator's Guide• Initial Setup

• Administration Area Overview

• Managing YouTrack Instance• Managing Basic Settings

• Managing Database• Backing Up Database

• Restoring Database from a Backup

• Changing Database Location

• Managing Text Indexing Settings

• Managing Projects• Creating New Project

• Importing a Project from JIRA

• Configuring a Project

• Managing Custom Fields• Supported Custom Field Types

• Creating and Editing Custom Fields

• Managing Enumerations

• Managing User Access

• Integrating YouTrack with External Tools


• Import to YouTrack• Import from Bugzilla

• Import from Mantis

• Python Client Library

• Import from a CSV File

• Import from Another YouTrack Server

• Import from Google Code Issue Tracker

• Import from Trac

• Integration with External Tools• Integration with Test Management Tools

• Integration with TestLink

• Integration with TeamCity• Configuring TeamCity Integration

• Executing Commands from a Comment to a VCS Change Commit

• Mapping Issues to VCS Change Commit

• Using TeamCity Integration

• Mailbox Integration

• LDAP Integration

• OpenID Integration

• OpenSearch Support in YouTrack

• FAQ

• Quick Start Guides• Quick Start Guide. Creating a New Issue

• Quick Start Guide. Using YouTrack Bookmarklet

• Quick Start Guide. Adding Attachments to an Issue

• Quick Start Guide. Using Screenshot Applet

• Quick Start Guide. Searching for Issues

• Quick Start Guide. Navigating Between Issues

• Quick Start Guide. Using YouTrack command window

• Quick Start Guide. Using Tags

• Quick Start Guide. Using Issue Filters

• Quick Start Guide. Watching Issues

• Quick Start Guide. Using Wiki Markup

• Quick Start Guide. Customizing Sidebar

• Search Query and Commands Reference• Command Grammar

• Search and Command Attributes

• Search Query Grammar

• YouTrack REST API Reference• General REST API

• Issues Related Methods• Create New Issue

• Get an Issue


• Get Issues

• Check that an Issue Exists

• Get Attachments of an Issue

• Get Comments of an Issue

• Get Links of an Issue

• Apply Command to an Issue

• Attach File to an Issue

• Delete an Issue

• Projects Related Methods• Get Accessible Projects

• Get Issues in Accessible Projects

• Get Issues in a Project

• Get Issue Priorities

• Get Issue States

• Get States Considered to be Resolved

• Get Issue Types

• User Related Methods• Log in to YouTrack

• Get Info For Current User

• Get User by Login Name

• Get Saved Searches for a User

• Administration REST API• Project

• GET Project

• GET Projects

• Project Builds• GET Builds

• PUT Project

• DELETE Project

• Assignees• GET Assignees

• GET Assignee Groups

• GET Individual Assignees

• Project Custom Fields• GET Project Custom Field

• GET Project Custom Fields

• POST Project Custom Field

• PUT Project Custom Field

• DELETE Project Custom Field

• Subsystems• GET Subsystems

• GET Subsystem

• PUT Subsystem


• DELETE Subsystem

• Versions• GET Version

• GET Versions

• POST Version

• PUT Version

• DELETE Version

• Users• GET User

• GET Users

• POST User

• PUT User

• DELETE User

• GET User Roles

• GET User Groups

• Groups• GET Group

• GET Groups

• POST Group

• PUT Group

• DELETE Group

• GET Group Roles

• Role• GET Role

• GET Roles

• GET Role Permissions

• Issue Link Types• GET Issue Link Types

• GET Issue Link Type

• PUT Issue Link Type

• POST Issue Link Type

• DELETE Issue Link Type

• Custom Fields• Prototypes

• GET Prototype

• GET Prototypes

• POST Prototype

• PUT Prototype

• DELETE Prototype

• Enumeration Bundles• GET Enumeration

• GET Enumerations

• POST Enumeration


• PUT Enumeration

• DELETE Enumeration

• Values• POST Value

• PUT Value

• DELETE Value

• Custom Field Types• GET Custom Field Type

• GET Custom Field Types

• Statistics• GET Browser Usage

• GET Telemetry

• Import REST API• Import Users

• Import Issues

• Import Links

• REST Import Sample


YouTrack Energy Documentation

This page last changed on Dec 30, 2010 by ivrina.

YouTrack Quick Start Guides

Creating a New IssueUsing YouTrack BookmarkletAdding Attachments to an IssueUsing Screenshot AppletSearching for IssuesNavigating Between IssuesUsing YouTrack Command WindowUsing TagsUsing Saved SearchesUsing Issue FiltersWatching Issues

Using Wiki Markup

Customizing Sidebar

YouTrack FAQ

Frequently Asked Questions

YouTrack Reference

Search Query and Commands Reference

Search Query Grammar (BNF)

Command Grammar (BNF)

Keyboard Shortcuts

YouTrack Administration

Installation and Upgrade Administrator's Guide

Integration with External Tools

YouTrack REST API

General REST APIAdministration REST APIImport REST API

Bug Reports, FeatureRequests, and Feedback

Report bugs and post feature requestsSend your feedbackDiscuss YouTrack

Legend

— new or recently updated document

YouTrack Demos

Issue Search

Using Commands

More demos

http://confluence.jetbrains.net/display/YTD3/Quick+Start+Guide.+Using+Saved+Searcheshttp://jetbrains.net/tracker/issues/JThttp://www.jetbrains.com/feedback/feedback.jsp?product=youTrackhttp://www.jetbrains.net/devnet/community/youtrack?view=discussionshttp://www.jetbrains.com/youtrack/documentation/demos/short/search/search_beta_demo.htmlhttp://www.jetbrains.com/youtrack/documentation/demos/short/commands/commands_beta_demo.htmlhttp://www.jetbrains.com/youtrack/documentation/


Keyboard Shortcuts


YouTrack is a keyboard-centric application and provides enough keyboard support to let you forget aboutusing the mouse in most cases. For almost any operation you need to do, wether it's creating, editing ornavigating between issues, commenting, changing attributes — YouTrack provides a shortcut. Shortcutslisted here are valid for YouTrack Energy version, and are divided by the modes of viewing and workingwith issues in YouTrack:

Error formatting macro: toc: java.lang.NullPointerException

Issues List

Win Shortcut Mac Shortcut DescriptionEsc esc ( ) Switch between search box and

issues list or Deselect any selectedissue in the list.

Down Down Move from the search box to thetop issue in the list.

Ctrl+Shift+Backspace ctrl( )+ +BackspaceHide/Show the left sidebar.Ctrl+Shift+1 ctrl( )+ +1Open/Close 'My Tags and Saved

Searches' drop-down menu.Up Up Move from the top issue in the list

of issues to the search box.End Go to the last issue on the page.Home Go to the first issue on the page.Ctrl+Right ctrl( )+RightGo to next page.Ctrl+Left ctrl( )+LeftGo to previous page.Ctrl+Shift+Right ctrl( )+ +RightGo to last page of issues list.Ctrl+Shift+Left ctrl( )+ +LeftGo to first page of issues list.Right Right Expand an issue in the list of

issues.Left Left Collapse an issue in the list of

issues.Space Space Select an issue in the list of issues.F2 F2 Open the highlighted issue for

editing.Alt+Ctrl+Shift+C alt( )+ctrl( )+ +CSelect ID or ID and Summary for

highlighted issue. Sequentially:select Issue ID, select Issue IDand summary, deselect all.

Enter or Open a highlighted issue in aseparate page (enters full issueview).

Ctrl+/ ctrl( )+/ Show keyboard shortcuts hints.

Full Issue View

Win Shortcut Mac Shortcut DescriptionEnter Enter (

or )Open a highlighted issue in aseparate page (enters full issueview).

Ctrl+Up ctrl( )+UpGo back to the list of issues.Ctrl+Right ctrl( )+RightGo to the next issue in the search

results.Ctrl+Left ctrl( )+LeftGo to the previous issue in the

search results.Ctrl+Shift+C ctrl( )+ +CSwitch to the Comments tab.Ctrl+Shift+H ctrl( )+ +HSwitch to the History tab.


Ctrl+Shift+L ctrl( )+ +LSwitch to the Links tab.F2 F2 Edit issue.Ctrl+Shift+1 ctrl( )+ +1Open/Close 'My Tags and Saved

Searches' drop-down menu.Ctrl+/ ctrl( )+/ Show keyboard shortcuts hints.Backspace Backspace Go back to the search results

page.

Command Window

Win Shortcut Mac Shortcut DescriptionCtrl+Alt+J or any letter ctrl( )+alt( )+J

or any letterOpen Command window

Ctrl+Alt+P ctrl( )+alt( )+PToggle preview mode on/off.Ctrl+Enter ctrl( )+(

or )Apply command.

Esc esc (esc.gif) Cancel command.

Create/Edit Issue

Win Shortcut Mac Shortcut DescriptionAlt+Ins orCtrl+Alt+Ins (Opera)

ctrl( )+N Create new issue.

F2 F2 Edit issue.Ctrl+Alt+J or any letter ctrl( )+alt( )+J

or any letterOpen the Command window.

Ctrl+Alt+C ctrl( )+alt( )+COpen a form to comment an issue.Ctrl+Alt+V ctrl( )+alt( )+VPaste a screen-shot from

clipboard.Ctrl+Enter ctrl( )+(

or )Submit changes.

Ctrl+Alt+A ctrl( )+alt( )+AOpen a dialog to add file to anissue.

Ctrl+Alt+S ctrl( )+alt( )+SOpen applet to take a screen-shotand attach it to an issue.

Ctrl+Shift+1 ctrl( )+ +1Open/Close 'My Tags and SavedSearches' drop-down menu.


Installation and Upgrade

This page last changed on May 25, 2010 by ivrina.

YouTrack Supported Environments

YouTrack on Linux

• Linux. YouTrack JAR as a Service° Linux. YouTrack JAR as a Service. Old Method

• Linux. JAR in Apache Web Server• Linux. JAR in Nginx Web Server• Linux. WAR within Servlet Container and Apache Web Server• Linux. WAR within Servlet Container and Nginx Web Server

YouTrack on Windows

• Windows. Installing and Running YouTrack as a Service• Windows. YouTrack JAR and Apache Web Server• Windows. WAR and Tomcat Servlet Container• Windows. WAR within Servlet Container and Apache Web Server


YouTrack Supported Environments

This page last changed on Sep 02, 2010 by ivrina.

This page describes the supported environments for YouTrack 2.0

Java Version

JRE / JDK 1.5

1.6 (Note: JRE 1.6 is bundled with YouTrack EXEdistribution)

Operating Systems Microsoft Windows

Linux / Solaris

Apple Mac OS X

Application Servers Apache Tomcat Tomcat 6.0+ (Tomcat 6.0.26 is bundled with

YouTrack EXE distribution)Mortbay Jetty Jetty 6.0+Caucho Resin Resin 3.1.9 and higherGlassfish Glassfish v3JBoss JBoss 4+

Database BerkeleyDB JE distribution bundles BerkeleyDB JE v.4.0

Web Browsers Microsoft Internet Explorer 8.0

8.0 Compatibility mode

7.0

6.x — All of the main functionality will workin IE 6; however, some of the visual effects willbe missing. In order to solve these issues werecommend you install Google Chrome Frame.

Mozilla Firefox 3.0, 3.5, 3.6Safari Safari 4Opera Opera Opera 10Google Chrome Chrome 4.0+ for Windows and Linux

Google Chrome for Mac OS does not currentlysupport applets, thus some functionality, e.g. takingscreenshots, will be missing.

Legend: = Supported; = Supported with some restrictions; = Not Supported

http://code.google.com/chrome/chromeframe/


YouTrack on Linux


• Linux. YouTrack JAR as a Service° Linux. YouTrack JAR as a Service. Old Method

• Linux. JAR in Apache Web Server• Linux. JAR in Nginx Web Server• Linux. WAR within Servlet Container and Apache Web Server• Linux. WAR within Servlet Container and Nginx Web Server


Linux. YouTrack JAR as a Service

This page last changed on Nov 23, 2010 by ivrina.

We provide two methods you could use as a basis to install and run standalone YouTrack JAR as a serviceon *nix-like machines:

• Recommended method, described here, on this page we use ourselves to run YouTrack JAR• Alternative method provided by Alexey Efimov

Installing Standalone YouTrack JAR as aService on Linux

A method described here uses Tanuki Java Service Wrapper.

Important!Currently provided method for adding a startup script is valid and tested for RedHat-like OSmachines. For Ubuntu, adding a start-up script might differ.

To install and run YouTrack standalone JAR distribution as a service on a Unix-like OS, werecommend to use the following procedure:

1. Create a user to run YouTrack (e.g. youtrack):

/usr/sbin/useradd youtrack

2. Download Tanuki Java Service Wrapper compatible with your CPU. For an Intel-based machines, youcan use the commands below:

cd ~youtrack wget http://wrapper.tanukisoftware.com/download/3.5.6/wrapper-linux-x86-64-3.5.6.tar.gz

3. Unpack downloaded archive to the home directory of the created user. We also recommend torename the wrapper's directory (e.g. 'standalone'), for usability purposes:

tar -xzf wrapper-linux-x86-64-3.5.6.tar.gz mv wrapper-linux-x86-64-3.5.6 standalone

The result wrapper's directory should have the following structure:

./standalone

./standalone/bin

./standalone/conf

./standalone/doc

./standalone/jdoc

./standalone/lib

./standalone/logs

./standalone/src

4. Copy YouTrack standalone JAR file to the wrapper's directory:

cp youtrack-.jar ~youtrack/standalone/

5. Create a soft link to the JAR file:

cd ~youtrack/standalone/

http://wrapper.tanukisoftware.com/http://wrapper.tanukisoftware.com/


ln -s youtrack-.jar youtrack.jar

6. Create system startup script in the /etc/init.d/ as 'youtrack':a. Download the following script template: youtrack_initd.template. This template is based on

a sample startup script included in the wrapper distribution.b. Change settings in the top section of the script to reflect your system environment.c. Save the edited template as the youtrack script in the /etc/init.d/ folder.

7. Replace an existing wrapper's configuration file ~youtrack/standalone/conf/wrapper.conf withthe following configuration file: wrapper.conf.

8. Run your newly created wrapper to test the installation:

/sbin/service youtrack start

Test checklist:

• YouTrack has started successfully• 'youtrack.pid' pid file has appeared in the ~youtrack/standalone/ folder• 'wrapper.log' log file has appeared in the ~youtrack/standalone/logs/ folder

9. Add the new startup script to the system startup scripts sequence:

/sbin/chkconfig --add youtrack

10. You may stop or restart YouTrack by following commands:

/sbin/service youtrack stop

/sbin/service youtrack restart

By default, the new YouTrack instance is configured to use TCP port 8080. You can change thissetting in the wrappers.conf file, or you can edit the configuration of the Nginx frontend.

http://confluence.jetbrains.net/download/attachments/36017643/youtrack_initd.template?version=1http://confluence.jetbrains.net/download/attachments/36017643/wrapper.conf?version=1


Linux. YouTrack JAR as a Service. Old Method


Prerequisites

• To run YouTrack Standalone via JAR distribution file, you need to have Java JDK 1.5 and higher.• YouTrack requires at least 512Mb of JVM heap memory. You can set the size of heap memory

via -Xmx parameter when starting youtrack-xx.jar from the command line.Otherwise, set the system default JVM heap size. As the YouTrack database grows you shouldincrease the JVM memory size.

• In order to open graphic attachments and render image thumbnails correctly, it isrequired to use Java in Headless Mode. To enable Java Headless Mode, you can use -Djava.awt.headless=true parameter in the command line, when starting YouTrack, or setjava.awt.headless system property. For more information about Java Headless Mode pleaserefer to the Using Headless Mode in the Java SE Platform article on Java official web-site.

Considering the above mentioned requirements, you can run YouTrack with the following command:

java -Xmx512m -Djava.awt.headless=true -jar youtrack-xx.jar

Installing YouTrack JAR as a Service Under Linux

Linux Scripts for Easy YouTrack Installation

Many thanks to Alexey Efimov for sharing the scripts provided in this guide.

To quickly install YouTrack from .jar distribution under Linux, perform the following steps underroot user:

1. Add a user:

adduser youtrack --disabled-password

2. Create a directory:

mkdir -p /usr/local/youtrack chown youtrack.youtrack /usr/local/youtrack

3. Create script init.d:

vim /etc/init.d/youtrack

4. Paste the following code into init.d:

#! /bin/sh ### BEGIN INIT INFO # Provides: youtrack # Required-Start: $local_fs $remote_fs # Required-Stop: $local_fs $remote_fs # Default-Start: 2 3 4 5 # Default-Stop: S 0 1 6 # Short-Description: initscript for youtrack # Description: initscript for youtrack ### END INIT INFO

export HOME=/home/youtrack

set -e

http://java.sun.com/developer/technicalArticles/J2SE/Desktop/headless/


PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin NAME=youtrack SCRIPT=/usr/local/$NAME/$NAME.sh

d_start() { su youtrack -l -c "$SCRIPT start" }

d_stop() { su youtrack -l -c "$SCRIPT stop" }

case "$1" in start) echo "Starting $NAME..." d_start ;; stop) echo "Stopping $NAME..." d_stop ;; restart|force-reload) echo "Restarting $NAME..." d_stop d_start ;; *) echo "Usage: sudo /etc/init.d/youtrack {start|stop|restart}" >&2 exit 1 ;; esac

exit 0

5. Save the script and grant it exec privileges:

chmod +x /etc/init.d/youtrack

6. Install init.d:

/usr/sbin/update-rc.d youtrack defaults

7. Create a run script:

vim /usr/local/youtrack/youtrack.sh

8. Paste the following code into youtrack.sh. Modify JAVA_HOME variable to correctly reference yourJava installation home directory (make sure to have JDK installed beforehand):

#! /bin/sh

export HOME=/home/youtrack export JAVA_HOME=/usr/local/java6

NAME=youtrack PORT=8112 USR=/usr/local/$NAME JAR=$USR/`ls -Lt $USR/*.jar | grep -o "$NAME-[^/]*.jar" | head -1` LOG=$USR/$NAME-$PORT.log PID=$USR/$NAME-$PORT.pid


d_start() { if [ -f $PID ]; then PID_VALUE=`cat $PID` if [ ! -z "$PID_VALUE" ]; then PID_VALUE=`ps ax | grep $PID_VALUE | grep -v grep | awk '{print $1}'` if [ ! -z "$PID_VALUE" ]; then exit 1; fi fi fi

PREV_DIR=`pwd` cd $USR exec $JAVA_HOME/bin/java -Xmx512m -jar $JAR $PORT >> $LOG 2>&1 & echo $! > $PID cd $PREV_DIR }

d_stop() { if [ -f $PID ]; then PID_VALUE=`cat $PID` if [ ! -z "$PID_VALUE" ]; then PID_VALUE=`ps ax | grep $PID_VALUE | grep -v grep | awk '{print $1}'` if [ ! -z "$PID_VALUE" ]; then kill $PID_VALUE WAIT_TIME=0 while [ `ps ax | grep $PID_VALUE | grep -v grep | wc -l` -ne 0 -a "$WAIT_TIME" -lt 2 ] do sleep 1 WAIT_TIME=$(expr $WAIT_TIME + 1) done if [ `ps ax | grep $PID_VALUE | grep -v grep | wc -l` -ne 0 ]; then WAIT_TIME=0 while [ `ps ax | grep $PID_VALUE | grep -v grep | wc -l` -ne 0 -a "$WAIT_TIME" -lt 15 ] do sleep 1 WAIT_TIME=$(expr $WAIT_TIME + 1) done echo fi if [ `ps ax | grep $PID_VALUE | grep -v grep | wc -l` -ne 0 ]; then kill -9 $PID_VALUE fi fi fi rm -f $PID fi }

case "$1" in start) d_start ;; stop) d_stop ;; *) echo "Usage: $0 {start|stop|restart}" >&2 exit 1 ;; esac

exit 0

9. Save youtrack.sh and grant it exec privileges:


chmod +x /usr/local/youtrack/youtrack.sh

10. Download the latest YouTrack JAR file (make sure to change accordintly):

sudo su youtrack -l -c "cd /usr/local/youtrack && wget http://download.jetbrains.com/charisma/youtrack-.jar"

11. Run YouTrack:

/etc/init.d/youtrack restart

YouTrack will run on port 8112.12. Install lighttpd1.5 server:

vim /etc/lighttpd/conf-available/20-youtrack.conf

13. To configure proxy, paste the following code:

server.modules += ( "mod_proxy_core" ) server.modules += ( "mod_proxy_backend_http" )

#$HTTP["host"] =~ "^youtrack\." { proxy-core.protocol = "http" proxy-core.backends = ( "localhost:8112" ) proxy-core.max-pool-size = 16 #}

Uncomment commented lines if you have virtual hosts for YouTrack on a multiple-site host.14. Add a symbolic link:

ln -s /etc/lighttpd/conf-available/20-youtrack.conf /etc/lighttpd/conf-enabled/20-youtrack.conf

15. Restart lighttpd:

/etc/init.d/lighttpd1.5 restart

You can now access YouTrack on port 80 via HTTP.

To upgrade YouTrack to a newer build, execute the following script (make sure to change tomatch the version of the build you're upgrading to):

sudo su youtrack -l -c "cd /usr/local/youtrack && wget http://download.jetbrains.com/charisma/youtrack-.jar" sudo /etc/init.d/youtrack restart


Linux. JAR in Apache Web Server

This page last changed on Oct 29, 2010 by ivrina.

Prerequisites






YouTrack Standalone JAR distribution bundles Jetty 6.1.x Servlet container. If you want to use it withApache HTTP server, you need to configure HTTP forwarding. When you run youtrack-xx.jar, you shouldspecify HTTP port in the command line. To allow users access your YouTrack instance via your Apache webserver, you need to forward this port to the web server via mod_proxy connector.

Jetty supports not only mod_proxy but also mode_jk connector to use AJP protocol. However, using themod_jk is not recommended by Jetty developers.

Official Jetty site provides extensive documentation about configuring and using Jetty with Apache WebServer via connectors.Please refer to the corresponding section for details:

• Configuring Apache mod_proxy with Jetty (recommended by Jetty)• Configuring AJP13 Using mod_jk or mod_proxy_ajp

When you configured the HTTP forwarding, just start YouTrack using the following command:

java [-Xmx512m] -jar youtrack-xx.jar

and then start your Web Server.

http://java.sun.com/developer/technicalArticles/J2SE/Desktop/headless/http://docs.codehaus.org/display/JETTY/Configuring+mod_proxyhttp://docs.codehaus.org/display/JETTY/Configuring+AJP13+Using+mod_jk


Linux. JAR in Nginx Web Server


Prerequisites






As long as YouTrack Standalone JAR distribution bundles Jetty 6.1.x Servlet container, the task ofconnecting YouTrack with Nginx web server narrows to specifying a location of YouTrack instance in theNginx configuration.

1. Locate nginx.conf file. By default, it's located in directory, e.g. usr/pkg/nginx2. In the nginx.cong add a new location block for your server, e.g.:

# youtrack servlet location /youtrack { proxy_pass http://:; }

Please note, that you should specify when you start youtrack-xx.jar in thecommand line.

3. Run YouTrack instance:

java [-Xmx512m] -jar youtrack-xx.jar

4. Start Nginx server

For more information about Nginx server configuration please refer to its documentation.For more details about Jetty servlet container please refer to its official site.

http://java.sun.com/developer/technicalArticles/J2SE/Desktop/headless/http://nginx.org/en/docs/http://jetty.codehaus.org/jetty/


Linux. WAR within Servlet Container and Apache Web Server


PrerequisitesCheck YouTrack Supported Environments page for supported servlet containers.

The general idea of using WAR distribution within a servlet container and Apache Web server is quitesimple:

1. Deploy youtrack-xx.war in your servlet container.2. Set up YouTrack in a servlet container (configure ports, connectors, etc.)3. Connect servlet container and Apache Web Server: set a port Apache should listen to for allowing

users to access YouTrack, set up connectors, etc.

These general steps will vary depending your servlet container specifics. Please refer to your containerdocumentation for details.

For details and specifics of using and configuring Apache Web Server, please refer to its documentationspace.

You can refer to the simplified description of configuring YouTrack within Tomcat servlet container andApache HTTP Server for OS Windows. Steps of the procedure are quite similar. Note that you have to beroot user to configure and run Apache HTTP.

http://httpd.apache.org/docs/http://httpd.apache.org/docs/


Linux. WAR within Servlet Container and Nginx Web Server


PrerequisitesCheck the YouTrack Supported Environments page for the list of supported servlet containers.

To use YouTrack WAR with Nginx web server:

1. Deploy youtrack-xx.war distribution in a servlet container. Refer to the documentation of yourservlet container for details. If you use Apache Tomcat, you can refer to the Windows. WAR andTomcat Servlet Container page. Though the procedure described is for OS Windows in particular, itssteps in Linux will be quite similar.

2. When your servlet container is set, specify a new location block in nginx.conf file. By default,it's located in directory, e.g. usr/pkg/nginx:

# youtrack servlet location /youtrack { proxy_pass http://:;

}

is a port specified for YouTrack within a servlet container.3. Start Nginx server

For more information about Nginx server configuration please refer to its documentation.

http://nginx.org/en/docs/


YouTrack on Windows


• Windows. Installing and Running YouTrack as a Service• Windows. YouTrack JAR and Apache Web Server• Windows. WAR and Tomcat Servlet Container• Windows. WAR within Servlet Container and Apache Web Server


Windows. Installing and Running YouTrack as a Service


YouTrack EXE distribution bundles Apache Tomcat application server and JRE 1.6, that is: No pre-installedsoftware is required to run YouTrack.

To install YouTrack as a Windows service, run downloaded youtrack-xx.exe and follow instructionsof the installation wizard.

Before reinstalling YouTrack with EXE distribution, we recommend you to stop currently runningYouTrack service. Open Control panel > Administrative tools > Services and stop 'YouTrackWeb Server' service.

Using EXE Distribution to Upgrade Existing YouTrack

Windows services launch from specific user accounts, for example, on Windows XP, services run underuser LocalService. When YouTrack is launched as a service, it looks for its issue database in thefollowing locations by default:

• On Windows XP: in "Documents and Settings\LocalService"• On Windows 7 and Vista: in the root directory of disk C

That means, if you use the EXE distribution to upgrade your current YouTrack installation:

1. Do not start YouTrack Service from the YouTrack Installation Wizard2. When installation is finished, open c:\\webapps\root\web-

inf\web.xml file and specify a path to your existing database via database.location parameter.3. When done, start YouTrack Web Server service via standard Windows Services tool.

Changing YouTrack Web Server Memory Settings

Being JVM application, YouTrack uses only JVM memory. By default, EXE installation sets Java heap size to512Mb. We recommend that you increase Java heap size as your database grows.

To edit JVM server options:

1. In the /bin start Tomcat's service configuration editor byexecuting the command

tomcat6w.exe //ES//YouTrack

2. Switch to the Java tab and then edit the Java Options (for more information see Tomcat 6documentation)

3. To change heap memory dedicated to the JVM, change the "Maximum memory pool" setting

http://tomcat.apache.org/tomcat-6.0-doc/windows-service-howto.htmlhttp://tomcat.apache.org/tomcat-6.0-doc/windows-service-howto.htmlhttp://confluence.jetbrains.net/download/attachments/36017577/YouTrack_tomcat_editor.png


Windows. YouTrack JAR and Apache Web Server


Prerequisites






YouTrack Standalone JAR distribution bundles Jetty 6.1.x Servlet container.

Generally there is no need in web server, you can run JAR as a java standalone process without using webserver.

However, if you need to connect Jetty and Apache Web Server, you will have to use Apache server withconnectors: mod_proxy, or mode_jk.Official Jetty site, contains extensive documentation about configuring and using Jetty with Apache WebServer via connectors.Please refer to the corresponding section for details:

• Configuring Apache mod_proxy with Jetty (recommended by Jetty)• Configuring AJP13 Using mod_jk or mod_proxy_ajp

When you configured Jetty to Apache Web Server connection, start YouTrack with the following command:


and then start your Apache Web Server.

http://java.sun.com/developer/technicalArticles/J2SE/Desktop/headless/http://docs.codehaus.org/display/JETTY/Configuring+mod_proxyhttp://docs.codehaus.org/display/JETTY/Configuring+AJP13+Using+mod_jk


Windows. WAR and Tomcat Servlet Container


PrerequisitesYouTrack Energy supports Apache Tomcat 6.0 and newer.

To deploy and run YouTrack WAR within Tomcat servlet container:

1. If you run Tomcat (e.g. as a Windows service), stop Tomcat instance before deploying YouTrack.2. Save youtrack-xx.war in the $TOMCAT_HOME$/webapps directory. Rename youtrack-xx.war file as

required before deploying. In the further examples we assume that the YouTrack servlet name is setto youtrack.war.

3. Start Apache Tomcat.4. In your web browser, navigate to http://yourserver:/youtrack.5. When the login form (http://yourserver:/youtrack/loginform) displays, enter

root/root as your default login/password pair.6. Complete the initial setup screen (http://yourserver:/youtrack-xx/setup):

a. Enter your user name and license key. If you need to evaluate YouTrack, request an evaluationkey.

b. Optionally, fill out all other initial settings. The step is recommended but you can specify thesesettings later on.

It is highly recommended you set the new password for the root user during the initialsetup. However, you can change the default password later, via root user's Profile.

For more information, please refer to Apache Tomcat official documentation.

http://tomcat.apache.org/download-60.cgihttp://yourserver:http://yourserver:http://yourserver:http://tomcat.apache.org/tomcat-6.0-doc/index.html


Windows. WAR within Servlet Container and Apache Web Server


PrerequisitesCheck YouTrack Supported Environments page for supported servlet containers.

The general idea of using WAR distribution within a servlet container and Apache Web server is quitesimple:

1. Deploy youtrack-xx.war in your servlet container.2. Set up YouTrack in a servlet container (configure ports, connectors, etc.)3. Connect servlet container and Apache Web Server: set a port Apache should listen to for allowing

users to access YouTrack, set up connectors, etc.

These general steps will vary depending your servlet container specifics. Please refer to your containerdocumentation for details.

For details and specifics of using and configuring Apache Web Server, please refer to its documentationspace.

In the next section, we provide a sample simplified procedure of configuring and running YouTrack withinTomcat servlet container and Apache HTTP Server.

YouTrack within Tomcat and Apache HTTP Server

To configure running YouTrack within Tomcat and Apache HTTP Server:

1. Deploy youtrack-xx.war in Tomcat servlet container:a. If you run Tomcat (e.g. as a Windows service), stop Tomcat instance before deploying

YouTrack.b. Save youtrack-xx.war in the $TOMCAT_HOME$/webapps directory. Rename youtrack-xx.war

file as required before deploying. In the further examples we assume that the YouTrack servletname is set to youtrack.war.

c. Start Apache Tomcat and check whether YouTrack is set up correctly and is available (in a webbrowser navigate to http://yourserver:/youtrack).

2. To connect Tomcat with a web server (in our particular case with Apache HTTP Server), install andconfigure mod_jk Tomcat connector. Apache provide detailed How-Tos for different web servers.Please refer to The Apache Tomcat Connector - Apache HowTo for detailed description ofconfiguring connectors between Apache HTTP server and Tomcat.

When done, you should be able to access YouTrack via your company'e web server at, e.g. http://yourcompanyname.com/youtrack address.

http://httpd.apache.org/docs/http://httpd.apache.org/docs/http://yourserver:http://tomcat.apache.org/download-connectors.cgihttp://tomcat.apache.org/connectors-doc/webserver_howto/apache.htmlhttp://yourcompanyname.com/youtrackhttp://yourcompanyname.com/youtrack


Administrator's Guide


Initial Setup

Administration Area Overview

Managing YouTrack Instance

• Managing Basic Settings• Managing Database

° Backing Up Database° Restoring Database from a Backup° Changing Database Location

• Managing Text Indexing Settings

Managing Projects

• Creating New Project• Importing a Project from JIRA• Configuring a Project

Managing Custom Fields

• Supported Custom Field Types• Creating and Editing Custom Fields• Managing Enumerations

Managing User Access

Integrating YouTrack with External Tools


Initial Setup

This page last changed on Jun 23, 2010 by ivrina.

When you run YouTrack for the first time, you will be automatically logged in as "root" user. Once youhave logged in, the Initial Setup page (base_URL/setUp) opens.

Root credentialsFor initial setup, you should set the root password. YouTrack will ask you the root password everytime you change settings.

First of all, you should read and accept License Agreement.

If you're using a EAP build, you can find a valid user name and license key at the EAP BuildInstallation page.

In addition, you can:

• Enter the base URL of your YouTrack installation so that links to issues in your e-mail/jabbernotifications can be constructed properly.

• Enable guest account in your YouTrack installation (you can start managing guest permissions afteryou'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 thesettings. You will be redirected to the Projects page (see Administering Projects).You can change these settings later using the Setup page (base_URL/settings).

Notes about 'root' userCurrently, the default root user account cannot be deleted. If you prefer to use another accountto administer YouTrack instance, configure new admin account properly, and then ban the rootaccount. For more details about administering user accounts refer to the corresponding section ofthis guide.

http://confluence.jetbrains.net/download/attachments/36017581/initialSetup.pnghttp://jetbrains.net/confluence/display/TSYSPUB/EAP+Build+Installationhttp://jetbrains.net/confluence/display/TSYSPUB/EAP+Build+Installation


Administration Area Overview

This page last changed on Aug 02, 2010 by ivrina.

Provided that you have sufficient permissions, you can enter YouTrack Admin area by clickingAdministration in the top right corner of YouTrack:

Admin area consists of the following pages:

• Projects. This is an overview of existing issue tracking projects, with options to create a newproject or import an existing project from a JIRA instance:

• Users. This is a list of registered YouTrack users with filters and a link to user registration page:

See Administering Users.• Groups. This page lists and describes existing user groups, and provides an option to create new

groups:

• Roles. This is a list of roles configured in the current YouTrack instance, with detailed permissionsassociated with them:

See Configuring Roles and Assigning Roles to Users.• Issue Link Types. This is a list of issue links configured in the current YouTrack instance:

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. "isduplicated by") and an outward name for the subject of a link (e.g. "duplicates").

• Setup. This page lets you configure license data, base URL of your YouTrack installation, enableguest account and notifications. This is the first page that is displayed after you have installedYouTrack:

http://confluence.jetbrains.net/download/attachments/36017582/admin_link.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_projects.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_users.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_usergroups.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_roles.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_issue_link_types.png


See 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:

See Administering Database 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:

Suspending text indexing is useful when a massive amount of documents to index considerablyimpairs server performance (for example, in peak hours). Another use case is to suspend textindexing 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 asthe number of available processors:

• Statistics. Use this page to view usage statistics for your YouTrack installation. Currently, it onlyhas one tab, Browsers Usage:

• Entity Browser. This is a simple YouTrack database viewer for troubleshooting purposes. Ifsomething goes completely wrong with your YouTrack installation, you might have to report someentity data from this page:

• JIRA Integration. This page incorporates JIRA integration settings:

http://confluence.jetbrains.net/download/attachments/36017582/tabs_setup.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_database.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_text_index_settings.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_system_info.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_statistics.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_entity_browser.png


See Importing a Project from JIRA.• LDAP Integration. This page helps configure YouTrack to allow users in your company to log in

using credentials stored in your directory service:

See LDAP Integration.• OpenID Integration. This page lets you enable any or all of five OpenID providers supported by

YouTrack:

See OpenID Integration.• TeamCity Integration. This page helps integrate YouTrack with JetBrains TeamCity for linking

issues to VCS commits and automatically filling "Fixed in build" attribute values:

See TeamCity Integration and/or TeamCity Integration Guide.

http://confluence.jetbrains.net/download/attachments/15800166/jira_integration.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_ldap.pnghttp://confluence.jetbrains.net/download/attachments/36017582/tabs_openid.pnghttp://www.jetbrains.com/teamcity/http://confluence.jetbrains.net/download/attachments/36017582/tabs_teamcity.png


Managing YouTrack Instance


This section covers general settings of the YouTrack instance you can specify:

• General YouTrack Settings• Database Settings• Text Indexing settings


Managing Basic Settings


This page covers administering of basic settings of YouTrack, available at Administration -> Setupsection:

!adminScreens^adminSetupTab.png|thumbnail!

License

Staring with version 2.0, YouTrack bundles 30-day evaluation license. When the license expires you caneither send request to prolong evaluation period for another 30 days or buy the new license. When youuse the evaluation license, YouTrack will display notification about the license expiry date.

System Settings

• Base URL — Enter application installation URL. This URL is used for constructing links in e-mailnotifications, RSS links, and for the bookmarklet. Guess URL

• Restricted Mode — this mode is intended to increase performance. When the check box isselected, the following features will be disabled:

° tracking of not viewed issues° tracking of new comments.

• REST API — select the check box to enable REST API. For detailed description of available REST APImethods, refer to the YouTrack REST API Reference

Visual Settings

Visual settings pane allows you to:

• Set up logo for your YouTrack instance. To change the default logo, click the Change link andselect the file to upload in the appeared dialog.

You can upload a JPG, GIF or PNG file. Default dimensions are 125x25 px. If the size of theuploaded page is larger, new logo will be resized automatically to the defaults.

• Limit the number of issues to be exported as HTML or CSV, or to be exported for the furtherprinting. By default, the limit is set to 500 issues. To change it, just enter a new value.

The limit is set to avoid the possibility to overload YouTrack instance.

User Settings

This block of settings allows administrator to enable and control the following features:

• User registration: when enabled, a user can create an account manually via registration page.Register a new account link appears on the Login page.

• Guest: when enabled, users can log in to YouTrack anonymously, as a guest user. To set uppermissions for a guest user, click the Manage guest permissions link. By default, guest user hasread-only permissions, e.g. viewing the list of issues, searching for issues, etc., but cannot create anew issue or change any attribute for existing issues.


Managing Database


Managing DatabaseYouTrack uses its own in-process database. By default, data files are saved to ${user.home}/teamsysdata directory.

• Backing Up Database• Restoring Database from a Backup• Changing Database Location


Backing Up Database


YouTrack database controls are available by clicking Database Backup in the Administration Area.

Specifically, you can back up YouTrack database right away or schedule backups using cron expressions(see cron expression syntax 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 databasebackup.

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

http://confluence.jetbrains.net/download/attachments/36019570/adminDatabaseBackup.pnghttp://www.quartz-scheduler.org/docs/tutorials/crontrigger.html


Restoring Database from a Backup


Important noteFor successful restoring, version of the backed up database should be the same or older than theversion of YouTrack, to which you restore this database.

To restore a database from a backup, proceed as follows:

1. Download a backup tar.gz file via web UI from the Administration > Database Backup page orlocate a needed backup file directly in the specified backup folder on the YouTrack server machine.

2. Stop YouTrack server instance.3. Extract the downloaded backup file to your database location. By default, the database is located

in the teamsysdata folder in the home directory of a user account, which starts YouTrack. You canchange default database location, for more details please refer to the Changing Database Locationpage.

4. Start YouTrack.


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:

YouTrack MainServlet jetbrains.charisma.main.ServletImpl database.location ${user.home}/teamsysdata ... ...


Managing Text Indexing Settings


This page lets you configure languages to take account of during text indexing, and provides a button tosuspend it:

Suspending text indexing is useful when a massive amount of documents to index considerably impairsserver performance (for example, in peak hours). Another use case is to suspend text indexing forcreating a backup right after you have imported a new project.

When the indexing suspended the corresponding note and the Resume button to re-start indexing aredisplayed.

http://confluence.jetbrains.net/download/attachments/36017583/tabs_text_index_settings.png


Managing Projects


Creating New Project

Importing a Project from JIRA

Configuring a Project


Creating New Project


Creating a New Project

To create a new empty project:

1. In the Projects page (base_URL/projects), click Create new project. The Create new projectwill be opened:

2. Enter project name and project ID

Please note, that a Project ID should not contain either a dash (-) or a slash ( /) symbol!

As a general rule, before creating projects on top of an empty YouTrack installation, it isrecommended that you configure roles, groups and users (in this particular order).

3. Enter the starting number. This number will be used as a suffix of an issue ID for the first issue inth# new project. Issue Id is composed from the project ID and a sequential number of an issue in aproject.

4. Select a user as the project lead. A project lead will receive notifications about all unassigned issuesin the project.

5. Select a user group for assignees in this project.6. Optionally, enter a description for the new project.7. When done, click Create. You can now proceed with configuring the project.

http://confluence.jetbrains.net/download/attachments/36017653/admCreateProject.png





YouTrack is able to import existing projects from JIRA 3.8-3.13.4, and Jira 4.0 and higher. A projectis imported along with user accounts that have access to it, and (optionally) roles, groups, and groupmemberships. See JIRA Integration for details on JIRA Integration features.To import an existing project from JIRA:

1. In the Projects page (base_URL/projects), click Import existing project from Jira.2. 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 JIRAversion:

• YouTrack plug-in for JIRA 3.8-3.9.3 (available at /_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.8.1-3.jar)

• YouTrack plug-in for JIRA 3.10-3.13.4 (available at /_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.10-3.jar)

• YouTrack plug-in for Jira 4.0 and higher (available at /_classpath/jira-plugin/jetbrains-youtrack-rpc-plugin-4.0.jar)

3. Install the appropriate YouTrack plug-in in your JIRA instance by following guidelines for "Version 1"plug-ins in Managing JIRA Plugins.

4. Make sure that remote API is enabled in JIRA and the YouTrack plug-in has appeared in the list ofJIRA plug-ins as "Charisma JIRA plugin".

5. Getting back to YouTrack, click Enable Jira Integration.6. 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:

7. To import groups, roles, and group memberships, select Import Security Settings.8. Click Import Project.

When you re-import a previously imported project, YouTrack only processes issues thathave been added or changed since.

http://confluence.atlassian.com/display/JIRA/Managing+JIRA%27s+Pluginshttp://confluence.atlassian.com/display/JIRA/Enabling+the+RPC+pluginhttp://confluence.jetbrains.net/download/attachments/15800166/jira_integration.png





To configure a project:

1. In the Projects page, click the name of a project that you want to manage.2. 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, 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 (clickAdd/remove groups), or both.The Full assignees list table shows all users who act as assignees in the current project byvirtue of group membership or per-user configuration. The Assigned by column lets you knowhow exactly a particular user has become an assignee in the current project:

• 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.)

Subsystems are generally used to differentiate between large, consistentproject components (such as "Notifications" in YouTrack's own issue trackingproject.) However, in many cases tags are just enough to group a set of similarissues. Unlike subsystems, tags can be created by users themselves (providedthey have sufficient permissions).

• Versions. Using this tab, you can create project versions, set release dates for them, markthem as released (you can reference released versions in "affected version" attribute) orarchived (you can search for issues related to archived versions but you can't referencearchived versions in issue attributes):

• Builds. Using this tab, you can set build names/numbers and build assembly dates. IfTeamCity integration is configured, the list of successfully assembled builds is automaticallygenerated in this tab:

• Custom Fields. Using this tab you can attach a custom field to the project. To add anexisting custom field, click the Attach custom field, select a field to add, select anenumeration if needed, and specify a default text for the empty field's value.

http://confluence.jetbrains.net/download/attachments/36017585/project_assignees.pnghttp://confluence.jetbrains.net/download/attachments/36017585/projects_versions.pnghttp://confluence.jetbrains.net/download/attachments/36017585/projects_builds.png


If there's no existing custom field, you can click Create new custom field link to navigate tothe Custom Fields section where you can create new custom fields and enumerations.

3. Click Save to save project settings.

http://confluence.jetbrains.net/download/attachments/36017585/attachCustomField.pnghttp://confluence.jetbrains.net/download/attachments/36017585/adminProjectCustomFields.png


Managing Custom Fields


YouTrack allows users to define their own custom attributes an addition to a predefined set of attributes(Priority, Type, Assignee, Subsystem, Fix version etc.) provided by default. These custom attributes canbe used for scheduling, references, hardware specifications or whatever else a user requires to efficientlytrack issues.

Custom Fields have the following parameters:

• Name — custom field name.• Type — custom field type defines format of the values allowed for a field. For the details about

supported types, refer to the Supported Custom Field Types page.• Private Access — if a field is set as "Private" it will be available for viewing and editing only to

users which have proper permissions: "Read Issue Private Fields" and "Update Issue Private Fields"respectively.

• Visible by default — if the option "Visible by default" is enabled for a field, it will be displayedin the Issues list by default. A user can choose to not display such field by configuring personalvisibility parameters.

• Auto Attached — if enabled, the custom field will be attached automatically to each project inYouTrack, by default. For more details, please refer to the Attaching Custom Fields to ProjectsAutomatically page.

The complete list of existing custom fields in the system is available on the Administration -> CustomFields -> Custom fields tab.

Each custom field can be used in multiple projects.

For further details about custom fields please refer to the following pages in this section:

Supported Custom Field Types

Custom field type defines format of the values allowed for a field.

Creating and Editing Custom Fields

This page covers general procedures of creating, editing and deleting a custom field in YouTrack.

Managing Enumerations

http://confluence.jetbrains.net/display/YTD3/Attaching+Custom+Fields+to+Projects+Automaticallyhttp://confluence.jetbrains.net/display/YTD3/Attaching+Custom+Fields+to+Projects+Automatically


Supported Custom Field Types


Custom field type defines format of the values allowed for a field. Currently, YouTrack provides you withthe following custom field types:

• build[1] — a custom field of this type allows user to select a build number from a predefined set ofbuild numbers (builds bundle).

• enum[*] — a field can contain several values from a predefined set of values (enumeration)• enum[1] — a field should contain one value from a predefined set of values (enumeration)• group[1] — custom field can contain one user group name from a predefined list of user groups• group[*] — custom field can contain one or more user group names from a predefined list of user

groups• state[1] — custom field allows user to set a state for an issue from a predefined set of issue states

(states bundle).• version[*] — custom field of this type should contain one or more versions from a predefined list

of versions.• date — this type allows user specify particular date as an attribute for an issue.• integer — a field can contain single value in integer format• string — a field can contain single value in string format


Creating and Editing Custom Fields


This page covers general procedures of creating, editing and deleting a custom field in YouTrack.

Creating a New Custom Field

To create a new custom field:

1. Open Administration -> Custom Fields -> Custom fields tab and click the Create custom fieldlink. The ** dialog will appear:

2. Specify a name for the new custom field.3. Select the type of the new custom field from the drop-down list.4. If needed, enable Private Access, Visible by default and Auto Attached options.5. To create new custom field with with specified parameters, click Save.

Now the new field can be used in any project. Please note that depending on the field type you mightneed to make additional configuring (create corresponding

Editing a Custom Fields

To edit an existing custom field, click the Edit link for the needed field and in appeared dialog changeany custom field parameter:

Deleting a Custom Filed

To delete existing custom field, click Delete link for a field to be deleted and then confirm thedeletion in the appeared dialog.

Please remember that if a field to be deleted has been used in a project, then after deletion all such fieldswill be deleted from issues and thus all set values for such will be lost. If a custom field to be deleted hasnever been attached to a project, it will be deleted without confirmation.

http://confluence.jetbrains.net/download/attachments/36017587/customFieldsCreateNew.pnghttp://confluence.jetbrains.net/download/attachments/36021230/cfEditDialog.png





Enumeration is a predefined set of values, which can be used in custom fields of enum[*]} and{{enum[1] types.


Please note that a single enumeration can be used in several custom fields in different projects.

Creating a New Enumeration

To create a new enumeration:

1. Open Administration > Custom Fields > Enumerations tab and click the Add enumerationlink.

2. In appeared dialog specify a name for the new enumeration and add needed values.

Values in the enumeration are shown in the following format = .Values should be specified one per line. If no description is provided, an equal sign with emptydescription will be added automatically. As you type in values, below the text field will be shownchanges to be made and two buttons - Apply and Revert:

Click Apply to save currently entered values in the enumeration and proceed with editing the list,click Revert to clear all currently not applied changes.

3. When done, click Save.

Editing and Deleting an Enumeration

To edit an existing enumeration, click its name in the list and then edit the list of values (one item perrow):

Highlighting Enumeration Values

YouTrack allows its users to highlight values in an enumeration thus using a color coding for such fields,making distinguishing between different field values visually easier.

To customize colors for values in an enumeration:

1. Open Administration > Custom Fields > Enumerations tab

http://confluence.jetbrains.net/download/attachments/36021233/cfAddEnumeration.pnghttp://confluence.jetbrains.net/download/attachments/36021233/cfAddEnumerationEditing.pnghttp://confluence.jetbrains.net/download/attachments/36021233/cfEditEnumerations.png


2. For any enumeration item you want to colorize, click the palette icon next the needed value andselect a color to highlight it:

When done, any attribute that uses a customized enumeration will be colorized in the Issues List aswell as in the full screen mode.

http://confluence.jetbrains.net/download/attachments/36021233/enumerationHighlight.png


Managing User Access


We suggest that you configure user access in the following order:

1. Create new roles or configure predefined roles.2. Create new groups or configure predefined groups.3. Assign roles to groups on a per-project basis.4. Configure group membership for YouTrack users.

Configuring Roles

A role in YouTrack is a set of permissions. Roles are applied to groups on a per-project basis (withinspecified 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 PermissionsAdmin All permissions includedDeveloper View existing issues; create, modify, assign, link,

and delete issuesAdd attachments to issues and delete themCreate commentsView and modify own user profileCreate, modify, and delete tags or saved searchesMark issues as watched and view lists of other userswho are watching issuesVote for issues and view lists of other users whohave voted for issues

Reporter Report new and view existing issuesRead public comments; create, modify and deleteown commentsView and modify own user profileCreate, modify, and delete tags or saved searches

Observer View public issuesRead 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 Rolespage.

To create a new role:

1. In the Admin Area, click Roles.2. Click Create new role.3. In the role editing page, enter a name and (optionally) description for the new role.

4. Assign permissions listed and described in the role editing page.5. Click Create.

Once you have created and/or configured necessary roles, create or configure user groups, and assignroles to them on a per-project basis.

http://confluence.jetbrains.net/download/attachments/36017588/roles__new_role.png


Configuring Groups

Creating a Group

The following procedure describes creating a new group. To edit an existing group, click its entry in theGroups page.To create a new group:

1. In the Admin Area, click Groups.2. Click Create new group.3. In the group editing page, enter a name and (optionally) description for the new group.

4. Select Auto Join to automatically add any new registered users to this group.5. Click Create.

Once you have created necessary groups, start assigning roles to them.

Assigning Roles to a Group

To assign a role to a group:

1. In the Admin Area, click Groups.2. In the Name column, click the name of a group that you want to assign roles to.3. In the group editing page, click Roles.4. In the Roles tab, click Assign role. The Assign Role dialog box opens.5. In the Role drop-down list, choose a role to assign.6. In the Projects combo box, select one or several projects to apply the selected role:

7. Click OK.

When you have assigned roles to a group, the Permissions View tab in group properties appears. Itshows all permissions assigned to the current group via different roles:

Once you have prepared user groups with properly assigned roles, start adding users into your groups.

Administering Users

Creating User Accounts

In YouTrack, users are expected to create their user accounts themselves.

http://confluence.jetbrains.net/download/attachments/36017588/groups__new_group.pnghttp://confluence.jetbrains.net/download/attachments/15800166/new_users_reporter.pnghttp://confluence.jetbrains.net/download/attachments/36017588/groups__permissions.png


If for some reason you need to create accounts on behalf of users, you can do it using the regular userregistration page at base_URL/registerUserForm. For your convenience, there's a link to this page justabove the list of users in the Admin Area:

Whichever user registration procedure you choose, you need to create and/or configure a group thatevery new user will join, assigning it adequate permissions. See Assigning Roles to a Group for details.

Importing User Accounts from JIRA

User accounts are imported from JIRA along with projects. See JIRA Integration for details.

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:

1. In the Admin Area, click Groups.2. Choose a group from the list of groups, and click Add User.3. In the Select User dialog box, select a user:

4. Click OK.

To add a user to a group from the Users page:

1. In the Admin Area, click Users.2. Find a user entry using filters in the Filter area.3. In the list of found users, locate a user that you want to add to a group.4. 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.5. Click Add to groups / Remove from groups.6. In the Select Groups dialog box, select one or several groups to add the user to:

7. Click OK.

Once you have added the user to one or several groups, click Permissions View for the list of specificpermissions that the user is granted via group memberships or own roles.

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:

1. In the Admin Area, click Users.2. Find a user entry using filters in the Filter area.3. In the list of found users, locate a user that you want to exclude from a group.4. Click Groups for the user entry in the list of found users.

http://confluence.jetbrains.net/download/attachments/36017588/tabs_users.pnghttp://confluence.jetbrains.net/download/attachments/36017588/user_to_group__Groups.pnghttp://confluence.jetbrains.net/download/attachments/36017588/user_to_group__Users.png


5. In the User Groups tab, click Unassign for a group that you want to exclude the user from.

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:

1. In the Admin Area, click Users.2. Find a user entry using filters in the Filter area.3. In the list of found users, locate a user that you want to assign a role to.4. 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.5. Click Assign role.6. In the Assign Role dialog box, choose a role to assign to the user:

7. Select one or several projects where you want to apply the role.8. Click OK.

Open the Permissions View tab for the list of specific permissions that the user is granted via his/herown roles or group memberships.

Miscellaneous

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

To merge two user accounts:

1. In the Users page, locate a user account that you want to merge with another user account.2. Click Merge for the user entry in the list of found users.3. In the Select User dialog box, select a user account to merge with:

Note that if you're merging a less privileged user account with a more privileged user account, theresulting user account gets the more advanced permissions.

4. Click OK.

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

To ban a user account:

1. In the Users page, locate a user account that you want to ban.2. 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:

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

http://confluence.jetbrains.net/download/attachments/36017588/role_to_user.pnghttp://confluence.jetbrains.net/download/attachments/36017588/merge_users.png


Integrating YouTrack with External Tools



TeamCity Integration

You can integrate YouTrack with your JetBrains TeamCity 5.0+ installation:

TeamCity integration brings the following advantages:

1. TeamCity adds links from issue IDs referenced in VCS commits to actual issues in YouTrack, lettingyou navigate between commits and issues, and view associated changes from any issue.

2. YouTrack can parse and apply commands provided in VCS commits to actual issues in YouTrack, thusletting you change any issue attributes without opening YouTrack and doing the needed changesmanually.

3. TeamCity automatically puts correct build numbers to "fixed in build" attributes of your issues afterthese builds have been assembled.

For more information and specific TeamCity integration guidelines, see Integration with TeamCity.

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 a Project from JIRA.Updating previously imported projects is basically done the same way that you import JIRA projects forthe first time.Users are able to log in with their JIRA credentials as soon as you have completed importing a projectfrom 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.

LDAP Integration

LDAP integration lets you use user credentials stored in your directory service to log into YouTrack:

For details please refer to the LDAP Integration page.

OpenID Integration

YouTrack lets you enable authentication through any or all of supported OpenID providers: Google, Yahoo,America Online, and BlogSpot.

For details please refer to the OpenID Integration page.

http://www.jetbrains.com/teamcity/http://confluence.jetbrains.net/download/attachments/36017589/tabs_teamcity.pnghttp://confluence.jetbrains.net/download/attachments/36017589/tabs_ldap.png


Import to YouTrack


Ensure REST API is enabled in the target YouTrack installation before starting import process. Thissetting is located on Administration > Settings screen (http:///settings).

• Import from Bugzilla• Import from Mantis• Python Client Library• Import from a CSV File• Import from Another YouTrack Server• Import from Google Code Issue Tracker• Import from Trac


Import from Bugzilla



Importing Issues from Bugzilla to YouTrackError formatting macro: toc: java.lang.NullPointerException

General Procedure

To import issues from Bugzilla:

1. Download the latest version of YouTrack's Python Client Library and unzip it.2. Install Python or Jython.3. Install mySQLdb Python Library.4. If needed, create a new mapping file to set the correspondence between source fields in Bugzilla

and YouTrack issue's attributes. This mapping file should be created in the \python\bugzilla directory. By default, the defaultBzMapping.py file is used. Formore details about structure of the library, please refer to the Python Client Library page.

5. Import issues from a file to YouTrack running the following command:

python bugzilla2youtrack.py target_url target_login target_pass bz_db bz_host bz_port bz_login bz_pass [bz_product]

The following command line parameters should be provided:

Parameter Descriptiontarget_url URL of the YouTrack server to which data should

be imported.target_login User name to log in to the target YouTrack server.

Note that the user should have administratorpermissions.

target_pass Password to log in to the target YouTrack server.bz_db Name of the source Bugzilla database. By default,

in Bugzilla if no specific changes were made, thename of database is bugs.

bz_host URL of the source Bugzilla database.bz_port Port to access the source Bugzilla database. If not

configured otherwise specifically, the port numberfor Bugzilla database is 3306, by default.

bz_login Username to log in to the source Bugzilladatabase.

bz_pass Password to log in to the source Bugzilladatabase.

bz_product Name(s) of the source product to be importedfrom Bugzilla.

If no product name provided, all products inthe database will be imported.

User accounts are imported from Bugzilla by user's email addresses. In YouTrack, an e-mail address auser provided in Bugzilla will be used as a login name for a user account. Passwords for newly imported(created) user accounts in YouTrack are randomly generated, that is: for the first login to YouTrack, a usershould provide his e-mail address and then click the link Restore password to create a new password forhis account.

By default, all data in Bugzilla is stored in cp866 encoding. If you have configured another encoding, thento import data to YouTrack correctly you will need to change the encoding parameter in your mapping file.

http://www.jetbrains.com/youtrack/tools/index.htmlhttp://www.python.org/download/http://wiki.python.org/jython/InstallationInstructions


Mapping Notes

Mapping Bugzilla Statuses and Resolutions

Both Statuses and Resolutions are imported in YouTrack as issue state:

Bugzilla's STASUS YouTrack'sissue state

"UNCONFIRMED" Open"NEW" "Submitted""ASSIGNED" "Submitted""REOPENED" "Reopened"

Bugzilla'sRESOLUTION

YouTrack'sissue state

"FIXED" "Fixed""INVALID" "Can't Reproduce""WONTFIX" "Won't fix""DUPLICATE" "Duplicate""WORKSFORME" "Can't Reproduce""MOVED" "Won't fix","LATER" "Won't fix"

Mapping Custom Field Types in Bugzilla with YouTrack

Bugzilla's CF_TYPE (numeric) Bugzilla's CF_TYPE YouTrack's CF Type"1" FIELD_TYPE_FREETEXT "string""2" FIELD_TYPE_SINGLE_SELECT "enum[1]""3" FIELD_TYPE_MULTY_SELECT "enum[*]""4" FIELD_TYPE_TEXTAREA "string""5" FIELD_TYPE_DATETIME "string""7" FIELD_TYPE_BUG_URLS "string"

Bugzilla's FIELD_TYPE_BUGID (numeric id - 6) will be imported to YouTrack as an issue link. If youprefer a different mapping, please define it manually in your configuration mapping file.


Import from Mantis



Importing Issues from Mantis to YouTrackError formatting macro: toc: java.lang.NullPointerException

General Procedure

To import issues from Mantis bug tracker:

1. Download the latest version of YouTrack's Python Client Library and unzip it.2. Install Python or Jython.3. Install Python library mySQLdb4. If needed, create a new mapping file to set the correspondence between source fields in Mantis

and YouTrack issue's attributes. This mapping file should be created in the \python\mantis directory. By default, the defaultMantis.py file is used. For moredetails about structure of the library, please refer to the Python Client Library page.

5. Import issues from a file to YouTrack running the following command:

python mantis2youtrack.py target_url, target_login, target_pass, mantis_db_name, mantis_db_host, mantis_db_port, mantis_db_login, mantis_db_pass, mantis_project mantis_project mantis_project

The following command line parameters should be provided:

Parameter Descriptiontarget_url URL of the YouTrack server to which data should

be imported.target_login User name to log in to the target YouTrack server.

Note that the user should have administratorpermissions.

target_pass Password to log in to the target YouTrack server.mantis_db Name of the source Mantis database.mantis_host URL of the source Mantis database.mantis_port Port to access the source Mantis database. If not

configured specifically, the port number for Mantisdatabase is 3306, by default.

mantis_login Username to log in to the source Mantis database.mantis_pass Password to log in to the source Mantis database.mantis_project Name(s) of the source projects to be imported

from Mantis.

Important notes

About sub-projects

If any Mantis project to be imported has one or several sub-projects, all of them are imported as a singleproject in YouTrack. If you want to distinguish issues of different sub-projects, you should specify theCREATE_CF_FOR_SUBPROJECT parameter in your mapping file. If this variable is enabled, then for all issuesin the target YouTrack project a new custom field "Subproject" will be created. As a value of this customfield, the name of a subproject will be set. For issues from the main project, the Subproject custom fieldwill be set as Undefined.

http://www.mantisbt.org/http://www.jetbrains.com/youtrack/tools/index.htmlhttp://www.python.org/download/http://wiki.python.org/jython/InstallationInstructions


About user accounts

Please note that YouTrack does not support importing usernames with spaces. For such usernames thespace sign will be replace with the underscore ("_") sign.

About encodings

By default, all data in Mantis is stored in cp866 encoding. If you have configured another encoding, thento import your data to YouTrack correctly, you need to change the encoding parameter in your mappingfile.

Mapping Notes

All mappings except Custom Fields, could be edited, if needed.

Mapping Mantis's RESOLUTION and STATUS

Both Statuses and Resolutions are imported in YouTrack as issue state:

Mantis RESOLUTION YouTrack State10 (open) "Open"20 (fixed) "Fixed"30 (reopened) "Reopened"40 (unable to reproduce) "Can't Reproduce"50 (not fixable) "Won't fix"60 (duplicate) "Duplicate"70 (no change required) "Obsolete"80 (suspended) "Incomplete"90 (won't fix) "Won't fix"

Mantis STATUS YouTrack State40 (confirmed) "Verified"

Mapping Mantis's PRIORITY, STATUS, and LINK TYPES

Mantis PRIORITY YouTrack Priority10 (none) "0" (Minor)20 (low) "0" (Minor)30 (normal) "1" (Normal)40 (high) "2" (Major)50 (urgent) "3" (Critical)60 (immediate) "4" (Show-stoper)

Mantis LINK_TYPES YouTrack's Link type0 (duplicate of) "Duplicate"1 (related to) "Rela