Add a System-wide Banner to YouTrack
You can add an informational banner to YouTrack that contains any notification that you want to show to all users in the system. For example, you can warn users about scheduled downtime for system maintenance.
Once users close the banner, it is not shown to them again.
The banner text is loaded from a file that you upload to your YouTrack server. YouTrack checks the banner file every minute. If you overwrite the existing file, the new banner content is loaded and shown to all users.
This procedure consists of two steps:
Create and Upload the Banner File
The banner file is a snippet of text with HTML markup. When you tell your YouTrack server to load the file, it inserts this snippet into the HTML of the web interface.
YouTrack reads and handles the HTML snippet as follows:
- The
_bannerChecksum_string in the sample is substituted with the checksum from the file when it is loaded on the server. YouTrack uses the checksum to determine when the file has been updated. - The REST call tells YouTrack that a user has closed the notification. YouTrack uses the checksum to display a new banner when the file has been updated.
To create and upload the banner file:
- Paste the following sample into a text editor:
<div style="background: red; font-size:16px; color: white"> YouTrack is the best issue tracker ever! <script type="text/javascript"> function rest() { $.ajax({ dataType: "text", type: "POST", url: "/rest/user/banner", data: { checksum: "__bannerChecksum__" } }).done(function( msg ) { if (window.confirm("Ok. Reload?")) window.location.reload(); }); } </script> <button id="close" onclick="rest();">Close Banner</button> </div> - Change the message text.
You can also modify the attributes that are applied to the text in HTML markup. The attributes in the sample display 16-point white text on a red background.
- Save the HTML snippet as a text file in a directory on your YouTrack server.
Point YouTrack to the Location of the File
Next, you need to provide the location of the banner file to YouTrack.
You specify the path with the jetbrains.youtrack.banner.path system property.
The method for setting this property vary based on your YouTrack installation.
| Installation | Instructions |
|---|---|
| JAR | If you run YouTrack from the command line, you add the system property as a Java parameter when you start the server.
The command to start the server should look something like this:
java -Djetbrains.youtrack.banner.path=/home/xxx/banner.txt -jar youtrack-7.0.jar 8080 |
| Servlet | If you run YouTrack in a servlet container, add the -Djetbrains.youtrack.banner.path system property to your servlet container.
For example, for Tomcat on Windows, add the system property in the JAVA_OPTS section of the catalina.bat file. |
| Windows Service (MSI or ZIP) | Pass the system property as an ad hoc start parameter from the command line.
The command to start the server should look something like this:
youtrack.bat start --J-Djetbrains.youtrack.banner.path=/home/xxx/banner.txt |
| OSX or Linux (ZIP) | Pass the system property as an ad hoc start parameter from the command line.
The command to start the server should look something like this:
youtrack.sh start --J-Djetbrains.youtrack.banner.path=/home/xxx/banner.txt |
You can set the path to the banner file for any installation while the server is running with the REST API.
Send the following POST request on behalf of the root user:
http://<YouTrack_Base_URL>/rest/user/banner/reload?path=/home/user/banner.txt