Admin Guide 3.0

Announcer for Jira, Bitbucket, and Confluence apps can be installed via the Atlassian Marketplace or the Universal Plugin Manager (UPM).

If you're upgrading from a version prior to 1.5

If you're upgrading from a version from prior to 1.5, please note that all of your announcements will become disabled when you upgrade. Simply visit the Administration Overview page and click Enable all (or select the announcements to enable).





 On This Page



Administration Overview

To access the configuration pages:

  1. Select the Cog menu  > Manage apps.

  2. Expand the entry for the Announcer app.

  3. Click Get Started.

Announcer for Jira, and Confluence involves global and announcement level configurations, both of which are explained in the succeeding sections. The Announcer is now integrated with Atlassian Statuspage, and thus, appropriate connection details must be provided. These are also explained in the relevant sections.

Announcer Configuration

Click ANNOUNCER FOR JIRA/CONFLUENCE/BITBUCKET > Announcements from the sidebar to view the Announcer Configuration page that displays all active/inactive announcements and allows you to create, edit, or delete an announcement. The Statuspage.io generated announcements, if any, can be identified as having the Statuspage icon () in the title.

From this page, you can click:

  • Preview () to preview an existing notification.

  • Reset (to reset the all counts for an existing active notification.

  • Edit () to edit an existing notification.

  • Delete () to delete an existing notification.

  • Report () to see an acceptance report for an existing notification.

  • Add another notification to add a new announcement.

Basic edit options:

Advanced edit options:

Confluence:

Jira:

Enter the following details:

Basic edit options



Name

Description

Name

Description

Title

The title of the notification in the U/I that is presented to the end user in the title bar of the browser window.

Description

An internal description of the announcement that is not displayed to the end user.

Status

Indicates whether the announcement is active (enabled) or inactive (disabled).

Show for Anonymous

Indicates whether this item should be displayed to anonymous users.

Notification Type

Banner - Displays the notification as a banner on every page until the end user dismisses it.

Full Page - Displays the notification as a "full page" acknowledgment (see list of URLS below that are not affected).

Dialog - Displays the notification as a dialog.

Flag - Displays the notification as a popup that appears in the top right hand corner of the screen until the user dismisses it.

 Full Page is not available for announcements created by Space (Confluence) or Project (Jira and Bitbucket Server) administrators.

Contents

Use the dropdown to select the desired format (HTML, Markdown, Plain Text) and then enter the body of the announcement.



Advanced edit options

Click Show advanced options... to display additional options.



Name

Description

Name

Description

Filter for specific space(s)

(Confluence only) If you want to target a specific space, select this checkbox and then select the space that should be used. To select multiple spaces, hold down Shift and then click each space.

Filter for specific project(s)

(Jira and Bitbucket only) If you want to target a specific project, select this checkbox and then select the project that should be used. To select multiple projects, hold down Shift and then click each project. For Jira: Only the projects that the current user has 'Browse' or 'Administer' permission for, are shown.

Filter for specific groups(s)

If you want to target a specific group, select this checkbox and then select the group that should be used. To select multiple groups, hold down Shift and then click each group. 

Notification icon

Choose this if you'd like an icon displayed next to the announcement title. Available icons are:

  • Error

  • Information

  • Success

  • Warning

For a Banner and Flag notification types, the border colors and icons change based on the icon selected from this list of options.

Enable time restrictions on announcement

Select this checkbox if you want the announcement to appear only within a specific date range. Once this checkbox is selected, additional controls will appear so that you can click the start date, hold down Shift, and then click the end date.

Button Text

If you want to change the text of the button, specify it here. If this field is left blank, the default text is used.

Enable the button after 5 seconds

Select this checkbox and the Dismiss button will become active after 5 seconds, ensuring the user has the opportunity to read the announcement before dismissing it.

Should the accept button be shown

This applies to Banner and Flag announcement types only and indicates whether the Accept button should appear. This is selected by default.

Show announcement upon every login 

Select this checkbox to display the announcement to the user upon every login.

Click:

  • Preview to preview the announcement in a new tab.

  • Save to save the changes made to the announcement.

  • Cancel to discard your changes.



  • Jira handles the targeted projects differently than Bitbucket handles Bitbucket projects and Confluence handles a space. A project is considered active in Jira if it is the last project the user visited.

  • When editing Target groups, the person who edits the announcement, views only those groups to which the user directly belongs to.

  • As a web browser session is used, it is possible for an anonymous user to view the same item repeatedly. The repetition is removed if the user logs in.



Minimizing Performance Impact

If a large number of Filtered Spaces or Projects announcements are created for Spaces or Projects that are not visited often, there can be some performance issues. 

The same performance issue can be encountered if many time-restricted announcements are utilized, which causes the token cache to be continuously flushed.

If such performance issues occur, it is recommended to convert to global fixed announcements.

Reports

For any given report, select the report icon () to display an Acceptance Report that shows who has accepted the announcement and who has not. Dwell time (i.e. how long an announcement was displayed before the user dismissed it) is displayed as a summary across all users and on a per user basis.

You can:

  • hover over the User Name link to view the user profile details of the respective user. 

  • use Export to CSV button on the top right corner to export the report to a CSV file.

Announcer Global Configuration

Click ANNOUNCER FOR JIRA/CONFLUENCE/BITBUCKET > Configuration from the sidebar to view the Announcer Global Configuration page where you can configure all the global parameters of all the announcements.

The options that can be configured are:

Option

Description

Default value

Option

Description

Default value

Usage Analytics Settings

Help Us Improve the Product

When enabled, it allows us to collect some usage data that will help us improve the product. To learn more about what is being sent, refer to Analytics Information. This configuration can also be turned off if you do not wish to share the information.

true

Notification Settings

Dialog Height

This allows you to change the default dialog height of Dialog announcements.

500

Delegation Settings

Allow project administrators to create announcements

Allows Space Administrators and Project Administrators to create their own announcements.

false

Bypass Full Page Announcements

Input a regular expression which, when applied, will 'skip' the verification of interstitial announcements. To maintain normal behavior, leave this field blank.

When this field is blank, the regular expression used is ^Jakarta Commons-HttpClient.+ (this allows the Application Links to pass through).

For additional information on regular expressions, you may want to visit RegExLib.com or the Regular Expression Test Page.

blank

HTML Settings

Add/Remove tags and attributes for styling the announcements

Allows you to configure global HTML tags and attributes. 

Refer to the image

Remind Me Later Settings

Enable Remind Me Later

Enable this option to remind the user of the announcement after a pre-set period of time. Disabling this option displays the announcement until the user selects Dismiss.

false

Remind Me Later Text

Allows you to add the reminder link text that informs the purpose to the user.

blank

Mute period

Specifies the amount of time (in minutes) for which you can mute the announcement.

240

Explanation text

Allows you to add the hover dialog text that helps the user understand the announcement in detail.

Refer to the image



Statuspage.io Integrations

Click ANNOUNCER FOR JIRA/CONFLUENCE/BITBUCKET > Statuspage.io integrations from the sidebar to open the Statuspage.io Integration page. The integration with Statuspage ensures that important information about critical systems and/or any incident updates is displayed across Confluence, Jira or Bitbucket. A list of all announcements, enabled or disabled, is displayed in this page. Before you establish a connection with Statuspage, you see:

Click the Cog () menu on the top-right corner, to connect to a Statuspage instance. 

 

All the options here are mandatory. The options that can be configured are:

Name

Description

Name

Description

Base URL

Enter the Statuspage URL here. This URL is used to connect to your Statuspage instance.

Statuspage.io API Token

Enter the Statuspage API token. To get this token:

  1. Login to Statuspage.io with your credentials.

  2. Click your profile in the left sidebar.

  3. Click API info.

  4. Copy Your API user key (click the 

     icon). Paste that value in this field.

Polling Frequency

Specify the time in minutes. This value specifies how frequently the application must communicate with Statuspage to get the latest updates.

Statuspage Link Prefix

Enter the text to be used to link the announcement with the Statuspage incident page. After this text, a link to the specific Statuspage incident is included. Clicking this link opens the Statuspage incident page in the browser.

Click Save to save the announcement or Cancel, if you do not wish to proceed. 

After providing the connection details, click Add a Statuspage Integration now to create an announcement integrated with the configured Statuspage page.

The options that can be configured are:

Name

Description

Is mandatory?

Name

Description

Is mandatory?

Announcement Configuration

Enable

Select to receive incident updates from the specified Statuspage instance.

No

Name

Enter a relevant name for the Statuspage announcement. Your Jira Administrator can refer to the integration with this name.

Yes

Description

Enter a descriptive text for the announcement that is not visible to users.

No

Announcement Type

Banner - Displays the notification as a banner on every page until the end user dismisses it.

Full Page - Displays the notification as a "full page" acknowledgment (see list of URLS below that are not affected).

Dialog - Displays the notification as a dialog.

Flag - Displays the notification as a popup that appears in the top right hand corner of the screen until the user dismisses it.

 Full Page is not available for announcements created by Space (Confluence) or Project (Jira and Bitbucket Server) administrators.

Yes

Notification Icon

Choose this if you'd like an icon displayed next to the announcement title. Available icons are:

  • Error

  • Information

  • Success

  • Warning

For a Banner and Flag notification types, the border colors and icons change based on the icon selected from this list of options.

Yes

Filter for specific project(s)

(Jira and Bitbucket only) If you want to target a specific project, select this checkbox and then select the project that should be used. To select multiple projects, hold down Shift and then click each project. For Jira: Only the projects that the current user has 'Browse' or 'Administer' permission for, are shown.

No

Filter for specific groups(s)

If you want to target a specific group, select this checkbox and then select the group that should be used. To select multiple groups, hold down Shift and then click each group.

No

Statuspage.io Configuration

Statuspage.io page

Select a page from the drop-down list. This list is populated with the pages available on your Statuspage instance.

No

Status(s)

By default, all statuses available in Statuspage are displayed here. Click X to remove unwanted statuses from the box.

Yes

Announcement EOL 

Select the time till which the announcement is valid. This value is referred to as the End of Life (EOL) of the announcement. This specified time (in minutes, hours, or days) disables the announcements after the latest update from Statuspage is received. At the same time, the Acceptance Report counts for the announcement are also reset.



Yes

Click Create to create the announcement or Cancel, if you do not want to proceed. Once a Statuspage announcement is created, you see it listed in the Statuspage.io Integration page. 

To create announcements for other Statuspage pages, click Configure a Statuspage announcement. You can integrate with multiple Statuspage pages, as required.

Active Statuspage.io incidents

Click ANNOUNCER FOR JIRA/CONFLUENCE/BITBUCKET > Active Statuspage.io incidents from the sidebar to open the Incidents page. All active Statuspage announcements are displayed here.

If there are no active incidents, the Incidents page shows:

After the configurations are made and the Announcer Series begins to receive incident updates, the Incidents page displays details such as, when the incident occurred, and, when the incident was last updated as shown:

Click the edit () icon to view the incident history details. You can turn off notifications if you do not want to receive any more updates.

Bitbucket-specific functionality

If you're using Atlassian Bitbucket, a list of a user's outstanding announcements is shown whenever a user does a Git pull/push (and there are changes to be applied).

URLs that are not affected

The Announcer app will intercept all page requests with the exception of the following paths:

URL

Product

Description

URL

Product

Description

/rest/*

All

REST URLs are not blocked

/plugins/servlet/upm

All

The Universal Plugin Manager (UPM) is not blocked

Need to circumvent the Cookie check?

The Interstitial announcements are cookie-based and every once in a while you might want to make requests that don't get intercepted. You can use either of the following means to do this:

  • Set the User-Agent in the Global Configuration (see above).

  • Set the User-Agent on your request.

Make sure to add in a "X-WITTIFIED-NO-CHECK" header, such as:

curl -H "X-WITTIFIED-NO-CHECK: ignore" http://my-confluence-site.example.com

Confluence and Jira Data Center

Any enabling/disabling/new Interstitial announcements might take up to one minute to be active across all nodes.

Slack deep link support

Starting in version 2.7, announcements can be configured to open the Slack desktop client with the help of Slack deep linking.

Below are the examples showing how to configure it:

  • To open the Slack desktop client

    <a href="slack://open">Open Slack</a>



  • To open the Slack desktop client for a specific team 

    <a href="slack://open?team={TEAM_ID}">Open Slack</a>



  • To open the Slack desktop client for a specific team and channel 

    Click this link to learn how to find Slack team and channel ids.


Need more help? Contact our support team.