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

The app leverages Jira's section message component. You define a rule consisting of a JQL query, a title, a description, and a visual style. When a user views an issue that matches the JQL query, the message is rendered at the top of the issue view.

1. Create a Rule: Use the admin panel to define your JQL conditions.
2. Compose Content: Write your guidance text using Markdown.
3. Select Style: Pick the appropriate visual indicator (e.g., Warning for missing fields).
4. Save: The rule is active immediately for the selected spaces.

Getting Started

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

1. Go to Apps > Manage your apps.
2. Find Special Messages and click on configuration.
3. Click Create New Rule.
4. Fill in the form fields:
   • JQL: status = "In Progress" AND assignee is empty
   • Title: Action Required
   • Description: Please assign this ticket.
   • Style: Warning
   • Spaces: Select the projects to apply this to.
5. Click Test JQL to make sure your query is valid.
6. Click Save.

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

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

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?

Verify your JQL query is valid and returns results in the issue navigator. Ensure you have selected the correct Space/Project in the configuration form.

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.