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 (window.location.href.includes('projectKey=')) {
    const urlParams = new URLSearchParams(window.location.search);
    projectKey = urlParams.get('projectKey');
  } 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]

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]

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]

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

[VVC]

Hello @Matthias Gaiser _K15t_ 

Would it be possible for you to share a sample code on how to post an announcement or note on a specific Kanban board page?

Your sample code for a project banner works, so it would be great to see a Kanban board banner.

[Matthias Gaiser _K15t_]

I'm sorry that I missed all the replies here. For some reason, I didn't watch the article myself - my bad.

@VVC - I've adapted the code above to also check the url for a projectKey parameter which enables it on Scrum and Kanban boards. The lines I've added are these:

} else if (window.location.href.includes('projectKey=')) {
  const urlParams = new URLSearchParams(window.location.search);
  projectKey = urlParams.get('projectKey');

[VVC]

Thanks @Matthias Gaiser _K15t_ for getting back to me. For any given JIRA project, we have multiple Kanban and Scrum boards. Currently there is no sweet spot to display the usage information on each board, as each one serves a different purpose. Hence, I wanted to check with you if there is any provision to tweak this code and display a custom banner with unique content on each Kanban board page?

[Matthias Gaiser _K15t_]

I see, @VVC. You can adjust the code above to something like this:

<div id="boardAnnouncement" style="display:none;margin:0;" class="aui-message aui-message-info"></div>

<script>
  document.getElementById('announcement-banner').style.padding = '0';
  const showBoardAnnouncement = function() {
    const urlParams = new URLSearchParams(window.location.search);
    boardId = urlParams.get('rapidView'); 

    if (boardId) {
      if (boardId === '97'){
        document.getElementById('boardAnnouncement').style.display = 'block';
        document.getElementById('boardAnnouncement').innerHTML = 'These are the instructions for the board.'; 
      } else {
        document.getElementById('boardAnnouncement').style.display = 'none';
      }
    }
  }


  //run it once after everything is initialized on the other pages
  addEventListener('DOMContentLoaded', (event) => {showBoardAnnouncement()});
</script>

This code checks if the url contains a rapidView parameter which contains the id of the board. You can set up various (else) if's with the different board ids to show or link to your instructions. In the code example, I'm adding a banner only for the board with the id 97.

Hope that helps, all the best for your projects. 

[VVC]

Thanks so much @Matthias Gaiser _K15t_ for sharing this code and it's working like a charm. To customize the Jira DC UI, it looks like HTML, JavaScript, and CSS are the primary methods.

What is the best recommended approach to customize JIRA UI? I see that Atlassian's Forge is also for deeper customization, using native UI elements.

[Matthias Gaiser _K15t_]

Hey @VVCthis code snippet is only a little hack around the announcement banner to plug-in at a well-defined point.

If you talk about JIRA UI compared to Jira DC UI, I assume, you're talking about Jira Cloud (a domain ending with .atlassian.net)? If you want to customize this, you can indeed check out Forge. This offers you a way to run your own extensions without the need of a separate back-end where to host them.

[VVC]

Sorry for the confusion, @Matthias Gaiser _K15t_ . I was referring to JIRA DC UI customization and NOT Jira Cloud.

[Matthias Gaiser _K15t_]

If you really want to go deeper into customization DC, Forge is not the right approach since that's Cloud only.

You can still develop your own little app which can extend the UI in many different places. Here's the documentation how to do so.

Note: Keep in mind that Atlassian is investing way more into the Cloud and sees the Cloud as the future place to be. So, I'd personally would think twice before customizing too much on my DC instance.