How to configure a project banner on Jira Data Center

Do you also have the need to communicate certain news to specific Jira project users only? E.g. you're gradually migrating from Jira Server/Data Center to Jira Cloud and need to inform your users that a certain project is migrated and they should rather work in Jira Cloud?

In this How-to, I'll explain how you can configure a project banner on a project or even issue level.

 

📘 Instructions

You need system administration permissions in order to configure the banner.

  1. Navigate to the announcement banner administration in Jira.
    1. Choose Administration > System.
    2. Select User Interface > Announcement banner in the System panel below.
  2. In the Announcement text area, enter the sample code below and adjust it to your needs. The sample code adds an issue-specific banner and a project-specific banner, depending on the context the user currently is in. You probably want to adjust these sections:
    1. The text inside the projectAnnouncement div. This is the text shown in a project context, e.g. the project configuration.
    2. The text inside the issueAnnouncement div. This is the text shown in an issue context, e.g. the issue view.
    3. The list of projects (projectsToAnnounce) where this text should be shown.
  3. Save your banner.
<div id="projectAnnouncement" style="display:none;margin:0;" class="aui-message aui-message-error">
This is the project banner for project <span id="announcementProjectKey"></span>.</div>
<div id="issueAnnouncement" style="display:none;margin:0;" class="aui-message aui-message-error">
This is the issue banner for issue<span id="announcementIssueKey"></span>.</div>

<script>
//enter the project keys of your migrated projects here
const projectsToAnnounce = ['FIRST','SECOND'];

document.getElementById('announcement-banner').style.padding = '0';
const showProjectMovedAnnouncement = function() {
require(['jira/issue','jira/api/projects'], function(issue, projects) {
const pageDetails = getPageDetails(issue);
if (projectsToAnnounce.includes(pageDetails.projectKey)){
if (pageDetails.issueKey) {
document.getElementById('issueAnnouncement').style.display = 'block';
document.getElementById('announcementIssueKey').innerHTML = pageDetails.issueKey;
} else {
document.getElementById('projectAnnouncement').style.display = 'block';
document.getElementById('announcementProjectKey').innerHTML = pageDetails.projectKey;
}
} else {
document.getElementById('projectAnnouncement').style.display = 'none';
document.getElementById('issueAnnouncement').style.display = 'none';
}
});
}

if (window.location.href.includes('jql=')) {
//run the script multiple times in the issue browser
setInterval(showProjectMovedAnnouncement, 500);
} else {
//run it once after everything is initialized on the other pages
addEventListener('DOMContentLoaded', (event) => {showProjectMovedAnnouncement()});
}

function getPageDetails(issue, projects){
let issueKey;
let projectKey;

const metaAjsIssueKey = document.querySelector('meta[name="ajs-issue-key"]');
//try to get issue key
if ((issue.getIssueKey && issue.getIssueKey())) {
issueKey = issue.getIssueKey();
} else if (metaAjsIssueKey && metaAjsIssueKey.content) {
issueKey = metaAjsIssueKey.content;
}

//try to get project key
if (JIRA && JIRA.ProjectConfig && JIRA.ProjectConfig.getKey) {
projectKey = JIRA.ProjectConfig.getKey();
} else if (projects && projects.getCurrentProjectKey && projects.getCurrentProjectKey()) {
projectKey = projects.getCurrentProjectKey();
} else if (issueKey) {
let matches = issueKey.match(/([A-Za-z]+)-\d+/);
if (matches && matches.length > 1) {
projectKey = matches[1];
}
}

return {
'issueKey': issueKey,
'projectKey': projectKey
};
}
</script>

🎨 Styling Tips

If you want to style your banner in a different way, you can also make use of the Atlassian User Interface library (AUI). This sample code uses, e.g. AUI's messages formatting by specifying the corresponding CSS classes.

 

⚙️ More Technical Background

  • This script uses Jira's Javascript API to determine the context where it runs in. Other solutions like this one determine the location via the URL which is doable, but you need to make sure that you're reaching every location.
  • In the Issue browser (Issues > Search for Issues), the announcement banner and therefore the above script is only triggered when the whole page loads and not a specific issue. By using setInterval in the code above, this rendering logic can be repeatedly executed - and therefore the announcement banner updates accordingly.

 

👤 Background Info

While working on a blogpost for improving communication about a phased migration of Jira, we had the need for such a project configuration banner - and thought we simplify it and share it with the broader Atlassian Community. If you're interested in our specific version how that banner looked like, check out our help docs.

 

📣 What's your feedback?

Let me know what you think about it - or what improvement tips you have.
And if that's a too hacky solution for you - or you want to have it on Cloud, checkout some marketplace apps.

3 comments

Matt Doar
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
May 2, 2022

This is clever! I feel like I might have used a ScriptRunner web fragment to do this some time in the past, but I'm not positive?

Ashley Roberts March 15, 2023

Sorry I am new to Jira and also HTML, but is there a way to have this code to have one message for a specific project and all the other projects in Jira to have a different message? When I use the following code underneath the original message the top line is the universal and the bottom message is the below code.

<p style="display: none;" id="MUAS">Demo Announcement</p>
<script>
if (window.location.href.indexOf("projects/Project Key") != -1) {
document.getElementById("MUAS").style = "display: block;";
}
</script>

I was hoping to be able to show one or the other depending on the project we are looking at.

Janelle_Calvert February 14, 2024

Thank you Matthias for sharing this with us it worked great to add a project specific banner to our phased migration.  We are seeing now though an error code pop up on projects not referenced by the code - especially when we go into the board configuration settings.  It doesn't seem to affect the function of the projects and is hopefully just a nuisance but wondering if anyone is finding the same and if they know how we can avoid it?

Error: undefined missing jira/api/projects

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events