Comment Status and UI

This spoke covers the comment status workflow, UI display options, use cases, accessibility, and cross-feature integration. For comment data structure and @mentions, see Comments and Annotations. For the full overview, see Multi-User Collaboration.

Comment Status Lifecycle

Comments use a three-state workflow to support approval processes and issue resolution:

Status Transition Rules

Who can change status:

• Comment author — can change their own comment status
• Entity owner — can change status of any comment on their entities
• Administrators — can change any comment status

Status change notifications: System notifies the original comment author, all thread participants, all @mentioned users, and the entity owner when status changes.

Status Change Email

Subject: Comment resolved: "Can you review the error handling logic?"

Hi Alice,

Your comment on "SAP to Salesforce" was marked as Resolved by Bob Taylor.

    Original comment: @bob.taylor Can you review the error handling logic?
    Bob's reply: Looks good! Add logging for the fallback path.

Status: Open → Resolved

View thread: https://mapify.contoso.com/integration/3fa85f64#comment-7c9e6679

UI Display Options

Comments can be displayed in three patterns depending on workflow needs:

Option 1: Inline Badge on Node (Minimalist)

Best for: Quick visibility without cluttering the graph.

┌────────────────────────┐
│  SAP to Salesforce     │ 🔵3  ← Comment badge (3 open)
│  Integration           │
│  Status: Active        │
└────────────────────────┘

<div class="node-badge comment-badge"
     aria-label="3 open comments on this integration">
    <i class="fas fa-comment" aria-hidden="true"></i>
    <span class="badge-count">3</span>
</div>

<!-- Hover tooltip -->
<div class="comment-tooltip" role="tooltip">
    <div class="tooltip-header">
        <strong>3 comments</strong> <small>Most recent:</small>
    </div>
    <div class="tooltip-body">
        <strong>Alice Johnson</strong> 2 hours ago<br>
        @bob.taylor Can you review the error handling...
    </div>
    <small class="tooltip-action">Click node to view all comments</small>
</div>

Badge colors indicate status:

• Blue border = open comments
• Green border = all resolved
• Gray border = all closed

Option 2: Side Panel (Contextual)

Best for: Reading and replying while viewing entity details.

┌──────────────────────────────┐
│   Entity Details   │
├──────────────────────────────┤
│  Integration: SAP to Sales.. │
│  Owner: Alice Johnson        │
│  Status: Active              │
│                              │
│   Comments (3)  │
├──────────────────────────────┤
│  ┌─ Alice Johnson (2h ago)  │
│  │ @bob.taylor Can you...    │
│  │ [Reply] [Resolve]         │
│  └─┬─ Bob Taylor (1h ago)   │
│    │ Looks good! I've...     │
│    └─── Alice (30m ago)     │
│         Great idea!          │
├──────────────────────────────┤
│   Add Comment       │
│  ┌────────────────────────┐  │
│  │ Type your comment...   │  │
│  └────────────────────────┘  │
│  [Cancel]  [Post Comment]    │
└──────────────────────────────┘

<aside class="entity-detail-panel" role="complementary"
       aria-label="Entity details and comments">
    <div class="panel-header">
        <h2>Entity Details</h2>
        <button class="btn-close-panel" aria-label="Close entity details panel">
            <i class="fas fa-times" aria-hidden="true"></i>
        </button>
    </div>

    <div class="entity-summary">
        <dl>
            <dt>Integration:</dt><dd>SAP to Salesforce</dd>
            <dt>Owner:</dt><dd>Alice Johnson</dd>
            <dt>Status:</dt>
            <dd><span class="status-badge status-active">Active</span></dd>
        </dl>
    </div>

    <div class="comments-section">
        <h3><i class="fas fa-comments" aria-hidden="true"></i> Comments (3)</h3>

        <div class="comment-controls">
            <select aria-label="Filter comments by status">
                <option value="all">All Comments</option>
                <option value="open">Open Only</option>
                <option value="resolved">Resolved Only</option>
            </select>
            <select aria-label="Sort comments">
                <option value="newest">Newest First</option>
                <option value="oldest">Oldest First</option>
            </select>
        </div>

        <div class="comments-list" role="list" aria-label="Comment threads">
            <!-- Comment threads rendered here -->
        </div>
    </div>

    <div class="add-comment-section">
        <h4><i class="fas fa-plus" aria-hidden="true"></i> Add Comment</h4>
        <form class="comment-form">
            <label for="comment-text" class="visually-hidden">Comment text</label>
            <textarea
                id="comment-text"
                name="commentText"
                rows="4"
                placeholder="Type your comment... Use @mention to notify team members."
                aria-describedby="comment-help"
                maxlength="4000"
                required></textarea>
            <small id="comment-help">Supports @mentions. Max 4,000 characters.</small>
            <div class="form-actions">
                <button type="button" class="btn-secondary">Cancel</button>
                <button type="submit" class="btn-primary">
                    <i class="fas fa-paper-plane" aria-hidden="true"></i> Post Comment
                </button>
            </div>
        </form>
    </div>
</aside>

Option 3: Modal Dialog (Full-Focus)

Best for: Extended discussions requiring focused attention.

┌──────────────────────────────────────────────────────────┐
│   Comments: SAP to Salesforce    │
│──────────────────────────────────────────────────────────│
│  Filter: [All] [Open] [Resolved]    Sort: [Newest ▼]    │
│                                                          │
│  (scrollable comment thread area)                        │
│  ┌── Alice Johnson (2h ago) [Open]                       │
│  │   @bob.taylor Can you review error handling?          │
│  │   [Reply] [Resolve] [Close]                           │
│  └──┬─ Bob Taylor (1h ago)                               │
│     │   Looks good! Add logging for fallback.            │
│     └── Alice (30m ago)  Great idea, done.               │
│                                                          │
│──────────────────────────────────────────────────────────│
│  [text area: "Post a comment..."]        [Post Comment]  │
└──────────────────────────────────────────────────────────┘

Comment Use Cases

Compliance Approval

1. Alice adds comment: "@compliance.officer — This integration handles PII. Please review before Thursday's release." [Status: Open]
2. Compliance officer reviews and replies: "Reviewed. Encryption meets GDPR Article 32. Approved for production."
3. Officer marks comment Resolved → Alice and integration owner notified
4. Saved View "Compliance Approvals" shows all Resolved comments for audit evidence

Incident Root-Cause Analysis

1. Bob adds comment: "This integration failed at 2:47 AM. Stack trace shows timeout on SAP connection." [Status: Open]
2. Team investigates and replies with findings
3. Alice adds fix details and marks Resolved: "Fixed: SAP endpoint URL changed. Updated config."
4. Comment preserved in audit trail for post-incident report

Architecture Decision

1. Charlie asks: "@alice.johnson @bob.taylor — Should we use REST or SOAP for this Service?" [Status: Open]
2. Discussion thread contains pros/cons from both
3. Decision made, rationale documented in thread
4. Marked Closed once implementation is complete — permanently preserves the decision rationale

Change Coordination

1. Team member adds: "DO NOT modify this integration before Friday 18:00. Deployment window #DEP-4521." [Status: Open]
2. Auto-reminder notification sent to entity owner 24 hours before window
3. Comment marked Closed after deployment completes

Best Practices

For Comment Authors

• Be specific — Reference field names, error codes, ticket numbers for context
• Use @mentions sparingly — Only tag users who need to take action
• Resolve when done — Mark Resolved to close the loop; notify stakeholders
• Provide context — New readers should understand the issue without external research
• Avoid "Thanks!" replies — Use the Resolve button instead to reduce noise

For Teams

• Define SLA for responses — "@mentions should be acknowledged within 4 business hours"
• Standardize approval language — "Approved for production" = Resolved status
• Archive old threads — Close Resolved comments after 30 days to reduce clutter
• Integrate with ticketing — Reference Jira/ServiceNow ticket numbers in comments

For Administrators

• Monitor comment volume — High comment count on an entity may indicate unclear documentation
• Export for compliance — Generate quarterly reports for audit trail requirements
• Set retention policy — Closed comments archived after 1 year (configurable)
• Enable notifications — Ensure email delivery for @mentions is working

Accessibility Considerations (WCAG 2.1 AA)

Keyboard Navigation

Screen Reader Support

• Comment threads: role="list" and role="listitem" for semantic structure
• Status badges: aria-label="Open comment" (not just color/icon)
• Avatars: alt="Alice Johnson avatar" on all profile images
• Action buttons: Descriptive aria-label="Reply to Alice Johnson's comment"
• @mention autocomplete: role="listbox" and role="option" on dropdown
• New comment notifications: aria-live="polite" for real-time announcements

Color Contrast

All status colors meet WCAG 2.1 AA (4.5:1 ratio) on white backgrounds:

Status is always indicated by icon + text + color (never color alone).

Reduced Motion

@media (prefers-reduced-motion: reduce) {
    .comment             { transition: none; }
    .mention-autocomplete { animation: none; }
    .notification-toast  { animation: none; }
}

Integration with Other Features

Saved Views

• Comment filters: Save views showing "Entities with open comments" or "Entities I'm mentioned in"
• Notification views: Auto-filter to entities with comments in last 24 hours

Search and Discovery

• Comment text search: Search includes comment content (e.g., "firewall rules")
• @mention search: commented-by:alice.johnson finds entities where Alice commented
• Status filter: comment-status:open shows entities with unresolved comments

Change Tracking

• Comment creation, edit, and delete events appear in EntityChangeLog
• Compliance reports include comment activity (who commented, when, on which entities)

Ownership and Team Management

• @integration-team expands to notify all team members
• Entity owner is auto-notified when first comment is added to their entity
• Unresolved comments on critical entities escalate to owner after 48 hours

Related Topics

• Multi-User Collaboration Hub — full feature overview
• Comments and Annotations — data structure, @mentions, threading
• Architecture and Presence — real-time broadcasting
• Scalability and Offline Editing — async email delivery
• Change Tracking and Audit Trail — comments in audit trail
• Audit Reports and Retention — compliance reporting