Special Messages for Jira

Overview

Special Messages is a powerful Atlassian Forge app designed to enhance your Jira experience by providing contextual guidance to your team members. This app serves as an intelligent assistant that helps users navigate complex processes by displaying targeted messages directly on the screen view based on JQL rules.

Key Features

How It Works

For the admin view, go to Marketplace apps by clicking on the Gear icon at the top right section of your Jira. You'll see the admin page of the app called Special Messages in your app list.

After configuring your messages, you do need to enable the panel on your view.

1. Navigate to any Jira issue.
2. Enable the App Panel: Click on the Gear icon next to the work item's Summary and enable Special Messages from the list as shown below.
   
3. Pin to Issue View (Optional but recommended): When the app is shown between the file list and comment section, you can click on the three dots (...) on the right side of the panel and enable it to show for all work items.

The app leverages Jira’s section message component and native flag notifications. You define a message consisting of:

• Title
• Description (written with Markdown)
• Display mode: either Issue Panel or Flag Notification
• Visual style
• JQL query, plus optional Show from and Show until dates
• Spaces and work types it applies to

Messages are checked again whenever the work item changes, so a message appears or disappears as soon as the work item starts or stops matching, without reloading the page.

When an issue meets the JQL criteria:

• If Issue Panel is selected, the message appears embedded close to the comment section of the issue view, with Markdown support.
  
• If Flag Notification is selected, a pop-up toast appears in the bottom left with the title and a stripped version of the description (plain text, no Markdown formatting).
  

Getting Started

To configure Special Messages, navigate to the app configuration in your Jira administration settings.

1. Go to Jira settings > Apps and open Special Messages.
2. Click New message. The editor opens with three steps:
   1. What people read: a title (Action Required), the message in Markdown (Please assign this ticket.), where it appears (work item panel or pop-up flag) and its style (Warning).
   2. When it appears: the JQL condition, for example status = "In Progress" AND assignee is empty. Click Check JQL to validate it and see how many work items match today. Optionally set Show from and Show until dates.
   3. Who sees it: pick spaces and work types, or leave them empty to show the message everywhere.
3. Check the preview on the right, and type a work item key under Try it on a work item to confirm the message shows where you expect.
4. Click Create message.

Managing Messages

The admin page shows every message as a card rendered the way people will see it, with where and when it applies and its JQL condition.

• Filters: All, Live, Scheduled (start date in the future), Paused (switched off) and Ended (end date passed), each with a count, plus a search box for titles, text and JQL.
• On/off switch: pause a message without deleting it, and switch it back on later.
• Edit, Duplicate (creates a paused copy to start a variation) and Delete.
• If another admin changed a message after you opened it, saving tells you so and lets you reload, instead of overwriting their change.
• Changes reach every work item within about a minute.

Message Types

Special Messages offers five distinct styles to help you prioritize and categorize information:

ℹ️ Information

Best for general guidance, helpful tips, or process explanations.

⚠️ Warning

Used for important reminders that need attention but do not block work completely (e.g., "Don't forget to attach logs").

❌ Error

Critical issues that require immediate action. Often used when a workflow transition is blocked or data is invalid.

✅ Success

Confirmation messages for completed tasks or successful validations (e.g., "Ready for Deployment").

📄 Discovery (Issue Panel-only)

Educational content to help users learn new processes or understand terminology.

This type is only available for Issue Panel display.

Markdown Examples

Here are some practical examples you can copy and adapt for your own workflows.

Example 1: Missing Required Fields (Warning)

**⚠️ Action Required**
You cannot transition this issue to **In Progress** without assigning it.
Please ensure you have:
- [ ] Assigned a **Assignee**
- [ ] Set the **Priority**
- [ ] Filled out the **Story Points** field

Example 2: Definition of Done Table (Information)

**ℹ️ Definition of Done for QA**
Check the following criteria before passing this item:
| Component | Status | Notes |
| :--- | :--- | :--- |
| Frontend | ✅ Ready | Visual regression passed |
| Backend | ✅ Ready | API endpoints documented |
| Mobile | ⏳ Pending | Waiting for verification |

_Contact the Tech Lead if any component is blocked._

Example 3: Blocked Workflow (Error)

**❌ Transition Blocked**
You cannot resolve this issue because **2 sub-tasks** are still open.
Please verify the status of the following items:
- [ ] Update database schema (DEV-102)
- [ ] Migrate legacy data (DEV-105)

All sub-items must be closed before proceeding.

Example 4: Educational Guide (Discovery)

**📄 Process Guide: Triage Phase**

**What is Triage?**
This phase ensures every ticket is categorized correctly before engineering starts work.

**Why am I seeing this?**
Your current status indicates the ticket is awaiting triage. Please set:
1.  **Team:** (Frontend, Backend, DevOps)
2.  **Estimate:** (T-shirt size: S, M, L, XL)

[Click here for the full internal documentation](https://your-company-docs.com/triage)

Troubleshooting

My message isn't showing up?

Open the message and use Try it on a work item with the key of that work item: it tells you whether the space, the work type, the dates or the JQL condition is stopping it. Also check that the message is switched on, and remember that changes can take up to a minute to appear.

A work item shows "A message could not be checked"?

The JQL condition of that message is no longer valid (for example a field or value was renamed or removed). Edit the message and click Check JQL to see the error.

Saving says someone else changed the message?

Another admin saved it after you opened it. Reload the messages, review their change, and edit again.

Markdown isn't rendering?

Ensure you are using standard Markdown syntax. Check for unclosed brackets or backticks that might break the formatting.

Can I use HTML?

No, for security reasons, the app supports standard Markdown syntax only.