Usage Guide

Jira Service Management Portal Support

Secure Notes for Jira fully supports Jira Service Management (JSM) portals, allowing customers and agents to create and manage secure notes directly within customer request views.

Key Features for JSM Portals:

• ✅ Automatic Portal Detection: The app automatically detects when it's running in a JSM portal context and adapts accordingly

• ✅ Customer Request Integration: Secure notes are seamlessly integrated with JSM customer requests

• ✅ Portal User Support: Both portal customers and Jira users can create and view secure notes

• ✅ Request Type Awareness: The app recognizes JSM request types and displays the secure notes panel appropriately

• ✅ Seamless Experience: The same secure note functionality available in standard Jira issues works identically in JSM portals

How It Works:

1. In JSM Portal Context: When viewing a customer request in a JSM portal, the "Secure Notes For Jira" app appears in the Apps section

2. Secure Notes Panel: The dedicated "Secure notes panel" is displayed below the request details

3. Create Notes: Portal users can create secure notes just like in standard Jira issues

4. View Notes: Both incoming and sent notes are displayed with the same UI and functionality

5. Automatic Context Handling: The app automatically:

   • Detects portal context via extension.portal and extension.request.key

   • Fetches customer request details using the Service Desk API

   • Transforms portal context to issue context for seamless operation

   • Handles both portal customers and Jira users transparently

Portal-Specific Behavior:

• For Portal Customers: When a customer (reporter) views their request, they can see and interact with secure notes

• For Agents: Jira users (agents) viewing the same request have full access to secure notes functionality

• Request Key Mapping: Portal request keys (e.g., SN-8) are automatically mapped to underlying Jira issue keys

• Context Transformation: Portal requests are automatically converted to issue context, ensuring all secure note features work seamlessly

Example Use Cases:

• Customer Support: Agents can share sensitive information (like temporary passwords or access codes) securely with customers through portal requests

• Internal Communication: Team members can exchange confidential information related to customer requests

• Secure Documentation: Store sensitive details about customer requests that shouldn't be visible in public comments

Note: The app maintains the same security guarantees in portal contexts as in standard Jira issues. All encryption, expiration, and access control features work identically.

Creating a Secure Note

1. Open any Jira issue or JSM customer request

   Open

   

2. Click on the "Secure Notes" panel

   Open

   

    

3. Click "Create New Secure Note"

   Open

   

4. Fill in the required fields:

   • Select recipients: Choose one or multiple users who can decrypt the note

   • Description: Enter a description of what you're sharing (required)

   • Your Secure Note: Enter the secret message content (max 10KB recommended)

   • Set Note Expiry: Choose expiration time (1 hour, 1 day, 7 days, 10 days, or custom date)

5. Click "Generate New Key" to create an encryption key

6. Key Storage (fallback): If you forget to copy the key at creation time (copying is detected by clicking the key field or the copy button), it is stored in your browser's sessionStorage (encrypted) so you can retrieve and copy it later from the same browser

   • ⚠️ Important: This is local browser storage only — if you clear storage or open the ticket in a different browser/machine, you won't be able to retrieve the key from storage

   • Prefer copying the key (click the key field or copy button) or sending it via email right after creation; use the sent notes panel to copy the key again if it was stored in sessionStorage

   • 🔒 Security Note: The key stored in your browser is useless by itself — even if you (the sender) or anyone else has the key, it cannot decrypt the note without the authorized recipient's account. The key only works in combination with the recipient's authorization — only the designated recipient can use the key to decrypt the note

     Open

     

7. Share the Key: Copy the encryption key (Copy Key button in sent notes) and share it securely with the recipient via Slack, Teams, email, phone, or another channel outside of Atlassian infrastructure.

   • ⚠️ DO NOT share the key through Jira comments, issue descriptions, or any Atlassian Cloud channels — that would violate Zero Trust (Atlassian would have everything needed to decrypt the secret).

8. Click "Create & Encrypt Note"

9. Email Notification: The recipient(s) will automatically receive an email notification with:

   • A direct link to access the secure note

   • The expiration date and time

   • Instructions on how to obtain the decryption key (you must share it separately)

10. The note will be automatically updated in the panel in real-time using @forge/realtime

Viewing a Secure Note

1. Open the secure note link (from email notification or issue panel)

   Open

   

2. Enter the decryption key (shared by the sender via secure channel outside of Jira/Atlassian Cloud — e.g., Slack, Teams, direct email, phone call)

   • ⚠️ Important: The key should never be shared through Jira comments, descriptions, or Atlassian Cloud channels, as this violates Zero Trust architecture

3. Authorization Check: The system verifies that you are the authorized recipient — only the designated recipient's account can decrypt the note

   • ⚠️ Access Control: Neither the sender nor administrators can decrypt the note — only the authorized recipient

   • If you're not the recipient, the decryption will fail even with the correct key

4. View the message content

   Open

   

5. Use "Copy and Close" to save the content and destroy the note

6. The note will be automatically destroyed after viewing or when expired

   Open

   

Important Security Notes:

• Only the recipient can decrypt: The encryption key is issued to the recipient, and authorization checks ensure only the authenticated recipient can access the note

• Key safety: If the key accidentally falls into wrong hands, it's not a security issue — the key alone is useless without the correct recipient's account authorization

• Purpose: The key ensures Atlassian Cloud cannot decrypt notes even if their infrastructure is compromised — they don't have sufficient information without the key

Email Notifications

The application automatically sends email notifications for important events:

1. When a Secure Note is Created:

   • Recipients receive an email with subject "🔐 A security note has been shared with you"

   • The email includes a direct link to access the note

   • The expiration date and time are clearly displayed

   • Instructions on how to obtain the decryption key are provided

2. When a Secure Note Expires:

   • Recipients receive an email with subject "⚠️ A Secure Note has expired and was deleted"

   • The email notifies that the note has been automatically deleted

   • Instructions to contact the sender if access is still needed

3. When a Secure Note is Deleted:

   • Recipients receive an email with subject "🗑️ A Secure Note has been deleted"

   • The email notifies that the creator has manually deleted the note

   • Instructions to contact the sender if access is still needed

Note: Email notifications are sent via Jira's notification system and will appear in the recipient's email inbox associated with their Jira account.

Audit and History Pages

The application provides comprehensive audit pages:

1. My History (/myHistory - accessible from global page):

   • View all your secure notes with pagination

   • See description, status, issue/project keys, and timestamps

   • Expand rows to view status history (CREATED, VIEWED, DELETED, EXPIRED)

   • Export all data to CSV format

     Open

     

2. My Issue History (/myIssue - accessible from global page):

   • Browse all issues that contain secure notes

   • Click on an issue to view detailed audit information

   • Export issue-specific data to CSV

     Open

     

3. My Project History (/myProject - accessible from global page):

   • View all projects with secure notes

   • Drill down into project-specific audit details

   • Export project data to CSV

     Open

     

4. User History (/userHistory - Admin only, accessible from admin page):

   • Administrators can view all users' secure notes

   • Select a user to see their complete history

   • Export user-specific audit data to CSV

     Open

     

All audit pages feature:

• Pagination (10 items per page)

• Expandable status history rows

• CSV export functionality

• Real-time data updates

• "Ask Rovo" button: Automatically opens the Rovo AI agent with a pre-configured prompt based on the current audit tab:

  • My History: Prepares an activity report for the current user, including notes created by them and shared with them

  • My Issue History: Prepares an activity report for the selected issue

  • My Project History: Prepares an activity report for the selected project

  • User History: Prepares an activity report for the selected user

Rovo AI Analytics

The application includes a Rovo AI agent that enables natural language queries about Security Notes data. Users can ask questions in plain English, and the agent will generate and execute SQL queries to provide insights.

📖 Technical Details: A detailed description of how Rovo works with SQL, including the secure "Guide + Guard" pattern, query validation, row-level security, and safety mechanisms, is available in this community article.

Features:

• Ask questions like:

  • "Show all users which I shared security notes with"

  • "Show my notes from last week"

  • "Prepare a report of all descriptions and who shared notes last month"

  • "Show top 10 users who created the most security notes" (Admin only)

  • "Show all security notes created in the last 30 days"

  • "Display all notes shared with me that are still active"

Security:

• Only read-only SELECT queries are allowed

• Queries must target only the security_notes table (no JOINs, subqueries, or references to other tables)

• JOIN operations are automatically detected and blocked using EXPLAIN query plan analysis

• Window functions (e.g., COUNT(*) OVER(...)) are not allowed and are automatically detected and blocked

• Non-admin users can only see notes they created or received

• Admin users have full access to all notes

• Sensitive fields are protected:

  • Encryption key: Never stored on backend, only known to the user who created it

  • encryption_key_hash: Stored for validation only (cannot be used to decrypt)

  • IV and salt: Stored in metadata but useless without the encryption key

  • These fields are never exposed in Rovo queries or any API responses

• Row-level security is enforced automatically

• Security columns (created_by, target_user_id) must be selected as raw columns for proper access control

How to use:

1. Quick access via Audit pages: Click the "Ask Rovo" button on any audit page (My History, My Issue History, My Project History, or User History). The button automatically opens the Rovo AI agent with a pre-configured prompt based on the current tab context.

2. Manual access: Open the Rovo AI assistant in Jira directly (agent "Security Notes analytics")

3. Ask questions about Security Notes using natural language

4. The agent will generate SQL queries and return results

5. Results are explained in natural language with summaries and highlights

Example queries:

• "Can you show all users which I shared security notes with?"

• "Show all users which I shared security notes with."

• "Report security notes from last month."

• "Show me top 10 users who created the most security notes." (Admin only)

• "Display all security notes created in the last 30 days."

• "Show all notes shared with me that are still active."