How to configure a project banner on Jira Data Center

[#1]

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.

[Matt Doar__ LinkedIn]

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?