INTRODUCTION

    The Simple Announcements Addon gives you the ability to display announcements in your Jira Cloud instance. These banners can be shown on Jira Dashboards, Issue screens, and in Servide Desk.

    If you're asking yourself why you would want to use this addon, the answer is simple:

    Atlassian has removed announcement banners from Jira Cloud, making the standard Jira announcement banner inaccessible to customers in Jira Cloud.
    As of this moment, there is no word from Atlassian on whether this feature will come back or not. There are several Issues being tracked in the public Atlassian Jira instances about this, but most of them are quite old and have not seen any activity from Atlassian in a long time.

    As such, this plugin currently provides one of the only ways to show Announcements in Jira Cloud at all.

    PREREQUISITES

    Simple Announcements doesn't have any special pre-requisisted besides having a Jira Cloud instance.

    There are however several known limitations that impact where Announcements can be displayed. Some of these limitations require specific setup as well. Take a look at the next section for more details.

    KNOWN LIMITATIONS

    The addon currently has a few limitations you should be aware of:

    - Due to several limitations with Jira Cloud, we can only show Announcements on the Dashboard, the Issue Details screen, and within Service Desk. Other screens in Jira are currently not supported since Atlassian doesn't provide any way for us to hook into those screens.

    - In order to display Announcements on the Dashboard, you will have to add our Announcements Dashboard widget to the relevant Jira Dashboard (like the System Dashaboard). Without this widget, our code doesn't get loaded, and the Announcements wouldn't be displayed on the Dashboard itself.

    - We are currently imposing a limit of 10 active announcements. An active announcement is one that is marked as "active". Active Announcements that are scheduled for the future count towards this limit. You can deactivate old or future announcements. Any Inactive announcements do not count towards this limit, and can have an unlimited number of inactive announcements.

    NOTE: this limit will be lifted in the future, as we improve our infrastructure, and get a better handle on the load requirements across larger Jira instances.

    USING SIMPLE ANNOUNCEMENTS

    Setting up the Dashboard Gadget

    Why Would I even want a Dashboard gadget for Announcements?
    The primary reason is twofold:

    1) It presents itself as a central place that pretty much every Jira user visits on a consistent basis, and thus seems like the perfect place to show a list of currently active announcements.

    2) It's the only way to show any kind of content in Jira Cloud. Atlassian imposes several limitations on addon developers, and limits where addons can display any data at all. As such, a dashboard gadget is needed to both, show a list of currently active announcements, and to show the announcement dialogs themselves.

    NOTE:

    Without the dashboard gadget, none of the Announcements would show on the Jira Dashboard, and would only display in the issue details screen, or Service Desk (if applicable).



    What functionality does the Dashboard Gadget provide?

    Once added to the System Dashboard (or any other Dashboard for that matter), the Announcer Dashboard Gadget is responsible to showing the announcement dialogs that a user should see. Additionally, it automatically shows a list of currently active announcements.

    As you can see in the screenshot, we can see the title for each announcement, along with a read status. Any announcements already seen and acknowledged are marked with a checkmark, while unread announcements have a view icon. This makes it easy for users to see which announcements are currently active, and revisit them if needed.

    Jira administrators will see a "Manage" button, which allows navigating to the Manage Announcements screen. Non-administrators will not see this button.

    How to setup the dashboard gadget

    Alright, now that we've sweet talked you into using our Dashboard Gadget, let's run through how to add it to the System Dashboard.

    From the main Jira Dashboard, click on "Jira Settings" in the left navigation bar, then "System", and then "System Dashboard".

    You should now see the System Dashboard along with actions in the top right for "Add Gadget". Click the "Add gadget" button, which will bring up the "Add Gadget" Dialog

    add button on system dashboard

    add gadget dialog

    In the search bar on the left, search for "Announcements", and click on the "Add gadget" button. The Announcer gadget is now added to the System Dashboard, and you can rearrange the Dashboard however you see fit, and place the Announcer Gadget where you wish.

    There is no need to save anything, as all the changes you make here are automatically saved. Once done, your dashboard gadget would most likely be empty, and look like this:

    view of the empty gadget

    Creating an Announcement

    Announcements can be created from the "Manage Announcements" screen. As an administrator, simply click on "Manage Announcements" in the main Jira navigation sidebar.

    manage announcements link in jira sidebar

    Or alternatively, use the "Manage" button from the Dashboard widget

    manage button on dashboard widget



    From the Manage Announcements screen, click on the "New Announcement" button to launch the creation screen.

    New Announcements are split into multiple settings.

    Announcement Type

    The announcement type determines the 'scope' of the announcement. This determines where the announcement will show up, and doesn't necessarily have anything to do with visuals. Read the Announcement Types section for a more detailed overview of the various types


    Announcement Style

    The Announcement style determines how the Announcement will look.

    A 'Banner' will show as a large, wide dialog with a solid background.

    A 'Dialog' will show a medium sides dialog with a white background and colored accents


    Announcement Color and Icon

    The color determines either the background color for Banner style announcements, or the accent color (icon color, button color, etc) for Dialog style announcements.

    The icon determines which icon you would like to show to the left of the announcement title.


    Title

    This is the title of the announcement and will always show as the first line, and separated from the announcement message with a horizontal rule


    Message

    This is the main content body of the announcement. It supports rich text editing. Find more details in the Rich Content section.


    Scheduling

    The start and end date allow you to schedule an announcement to start in the future, and/or end at some specific point in time. Read the Scheduling section for more details.


    As you fill out the various parts of the creation screen, you can always Preview your announcement to see how the choices you made impact the visuals and final result of your announcement.

    Once you're satisfied, save the announcement, and it will become effective immediately. Once saved, the announcement type, and visiblility settings of the announcement become locked in, and cannot be changed when editing. Only styling and content can be changed when editing an announcement.

    NOTE:

    For performance reasons, and to provide a better user experience, our addon uses caching quite extensively. As such, it can take a minute or three before your announcement is visible to users.

    Different Types of Announcements

    The announcement type has little to do with how the announcement looks, and more specifically determines the 'scope' of the announcement. By which we mean 'who' can see the announcement.

    Type Description
    Global Global Announcements are shown to all authenticated Jira users and all Service Desk customers in all projects, and service desk portals.

    The announcement will show on the System Dashboard (if you added our gadget), on the issue details screen, the service desk portal, and the service desk ticket screen.

    Anonymous users, not authenticated to your Jira instance will not see Global announcements.
    Public Public Announcements are only shown to anonymous users that have not authenticated to your Jira instance. This includes the System Dashboard, as well as issue details screens if your Jira instance is public.
    Customer Customer Announcements are specifically scoped for Service Desk projects.

    For these announcements, you select which service desk project you wish to make your announcement in, and which of the service desk screens should show it.

    This type of announcement is not shown to your Jira users (neither globally, nor in the specific project you selected). Instead, it only shows to Service desk customers.

    Announcement Visibility

    Announcement Visibility is generally determined by the Type of announcement you're creating. Both Global and Public announcements show on every screen possible, except that Global announcements only show to authenticated users, while Public announcements only show to unauthenticated users.

    You'll notice that neither of those 2 options let you specify specific projects to announce anything to. At the moment, Customer Announcements are the only type that let you specify a project, and select which screens to show the announcement on.

    Customer Announcements are specific to Service Desk, and as such, can only be shown in service desk projects, and the announcement is only shown to Service Desk customers. Your Jira users would not see the announcement.


    Project Specific Announcements

    We are currently working on project specific Jira announcements, which will allow you to select one or more projects, and which screens within that project to display the announcement on.

    We are hoping to have this completed sometime in Q1 of 2019.
    If you have a need for this type of announcement, let us know, as we would love to have a chat with you to better understand your particular use-case.


    QUESTION: WHAT ABOUT OTHER SCREENS?

    At the moment, Atlassian doesn't provide many locations for addon developers to inject content to. As such, we are restricted to the few locations we already support. Once Atlassian adds more locations in the UI, we will add them to this addon.

    Announcement Styling

    Announcement styling and visuals allows you to change the look and feel of your announcement.

    The style determines the shape and visual template of the announcement, while the color and icon are accents within each style.

    Banner

    Banner announcement are still dialogs, but they are wider, and have a solid background.
    This would be the result of a red banner with a warning icon:

    Dialog

    Dialog announcement are more subtle dialogs with a white background and colored accents.
    This would be the result of a green dialog with a globe icon:

    Style, color, and icon can always be changed, even after a banner has been created.

    Embedding Rich Content

    Announcements use a rich text editor, and provide the ability to embed rich content like sub-headings, colored text, lists, tables, and links.

    At the moment, announcements don't support images and user mentions yet, but this is functionality we are evaluating for a future iteration along with other rich content and templates.

    Scheduling Announcements for specific dates

    All announcements can be scheduled to start and/or end on specific dates. On the announcement create/edit screen, you will see a Scheduling section that allows setting the start and end date:

    Using the start date allows you to set when an announcement should begin showing to users, while using the end date allows you to set when an announcement should stop being shown to users.

    Both date fields are optional. This allows you to create announcements that start on a specific date, but are open ended, or to create announcements that start right away, but end on a specific date.

    The scheduled date of announcements can be changed when editing an announcement, and the schedule will be adjusted immediately. Do note that due to caching, it can take a minute or three for the changes to take effect.

    Announcements with a schedule date in the future have a status of "Scheduled", and will only be visible to Admin users on the Manage Announcements screen. Regular users will not see these announcements.

    Once the schedule for an announcement dictates that it should be shown to users, we transition the announcement to an 'active' state, at which point users will see it.

    Similarly, when an announcements schedule dictates that it should no longer be shown to users, we transition it to an 'inactive' state, at which point regular users won't see it anymore, and only admin users can see it.

    Dismissing Announcements & Read Receipts

    Jira users will be presented with Announcement dialogs on the Jira Dashboard, as well as issue details screens.

    Each announcement has a "dismiss" button. This allows the user to acknowledge an announcement and mark it as read. Behind the scenes, we note the fact that this user marked an announcement as read, and in the future, don't show this same announcement anymore.

    It is possible for users to hit the Escape key on their keyboard to exit out of an announcement. This, however, does not mark the announcement as read, and the user will be presented with the same announcement again when the next screen loads.

    NOTE:

    Users can always view active announcements from the Dashboard gadget, even if they have already marked them as read.

    QUESTION: CAN I SEE WHICH USER HAS SEEN AN ANNOUNCEMENT?

    The short answer: not yet.

    While we are currently tracking which user has seen an announcement, there is no way for an admin to see this data yet. It is something we are planning on adding in Q1 of 2019 however.

    Editing an Announcement

    To edit an announcement, simply navigate to the Manage Announcements screen, and either click the edit button for the announcement, or view the details of an announcement and click the edit button from the details screen.

    This will bring up the announcement edit screen

    You might notice that the Announcement Type only shows a single option. This is intentional. Announcement Type, as well as Project visibility can only be changed when an announcement is created. Once created, those settings cannot be changed.

    The rest of an announcement can be changed at any time.

    When editing an existing announcement, we automatically reset all of the existing read receipts, so any user that has already seen this announcement will see it again with the changes you made.

    Activating/Deactivating Announcements

    Announcements can either be active, scheduled, or inactive.

    Active announcements are the ones currently being shown to users, while inactive announcements typically have an expired scheduling date.

    To move a scheduled announcement to be active, simply change or remove the schedule.

    To make an inactive announcement active again, either remove the schedule, or change it to fall into the current date.

    There is no specific action to deactivate an announcement. You would simply delete it to remove it.

    Deleting an Announcement

    Deleting an announcement can be done from the Manage Announcement screen.
    Simply click on the delete button, and confirm the deletion.

    Once deleted, we remove the announcement from our system, and clear all read receipts.

    IMPORTANT:

    There is no undo functionality. Once confirmed, a deleted announcement is irrevocably removed and cannot be recovered anymore.

    ADVANCED FUNCTIONALITY

    Multiple Active Announcements

    Simple Announcements makes it possible to have multiple announcements active at a time.
    Either intentionally, by creating multiples, or by scheduling announcements with an overlap.

    When this happens, the user is presented with 1 announcement at a time, and once a user dismisses the currently showing announcement, we show the next one, until there are none left to be acknowledged.

    NOTE:

    It is possible for users to hit the Escape key on their keyboard and dismiss the announcement dialogs. Due to technical limitations in Jira cloud, sometimes all of the announcements will be dismissed at once.

    These announcements are not marked as read, and only hidden from the current view. When the user reloads the screen, or visits another screen, all of the open (unread) announcements are displayed again.

    Showing Announcement only in Service Desk

    Simple Announcements allows you to create announcements that only show to Service Desk customers.

    To do so, simply follows the steps for creating an announcement, and select the "Customer" type announcement.

    This will present you with a selection of Service Desk projects, and whether you want the announcement to show on the Service Desk portal itself and/or the Service Desk ticket screen.

    IMPORTANT:

    Customer Announcements are only shown in the Customer views of Service Desk. As such, users viewing the corresponding Jira issue will not see the announcement. Only customers will.

    Showing Announcement to Public Users

    To create a public announcement simply follows the steps for creating an announcement, and select the "Public" type announcement type.

    Public announcements are only shown to anonymous (unauthenticated users). Logged in Jira users will not see a public announcement.