Notes & Comments
RAMP provides two distinct communication systems during execution: Execution Notes (editable, shared scratchpads) and Execution Comments (immutable, append-only logs). Both exist at the instance level and at the individual step level, giving teams flexible ways to document observations, issues, and decisions throughout a procedure.
Execution Notes vs. Execution Comments
Section titled “Execution Notes vs. Execution Comments”Understanding the difference between notes and comments is important for effective team communication during execution.
| Feature | Execution Notes | Execution Comments |
|---|---|---|
| Editability | Editable — content can be updated over time | Immutable — once posted, cannot be changed or deleted |
| Cardinality | One note per scope (one per instance, one per step) | Multiple comments per scope (append-only log) |
| Purpose | Shared scratchpad for evolving information | Permanent record of observations and decisions |
| Concurrency | Field locking prevents simultaneous edits | No locking needed; comments are independent entries |
| Best for | Running status updates, checklists, known-issue lists | Point-in-time observations, handoff notes, decision records |
Instance-Level Execution Notes
Section titled “Instance-Level Execution Notes”An instance execution note is a single, editable rich-text document shared across the entire instance. It functions as a living scratchpad where team members can maintain running status information.
Creating and Editing
Section titled “Creating and Editing”- Open the instance in the execution view
- Navigate to the Notes panel (right side of the execution view)
- Click into the note editor on the left side of the panel
- Write or update the note using the rich text editor
- Changes are saved automatically and broadcast to all connected users via SignalR
Field Locking
Section titled “Field Locking”To prevent conflicting edits, RAMP uses a field-locking mechanism:
- When you click into the note editor, you acquire a lock on that field
- Other users see a lock icon with a tooltip reading “Locked by [Your Name]”
- The lock releases automatically after 30 seconds of inactivity or when you click outside the editor
- Only one user can edit the instance execution note at a time
Permissions
Section titled “Permissions”Editing the instance execution note requires the EditInstanceExecutionNote permission. The following roles have this permission:
- Instance Head
- Deputy Head
- Executor
- Editor
Observers have read-only access.
Read-Only on Terminal Status
Section titled “Read-Only on Terminal Status”When an instance reaches Completed or Cancelled status, the execution note becomes read-only. The note content is preserved but no further edits are allowed.
Instance-Level Execution Comments
Section titled “Instance-Level Execution Comments”Instance execution comments form an immutable, append-only log for the instance. Each comment captures a point-in-time observation with the author’s identity and a timestamp.
Adding a Comment
Section titled “Adding a Comment”- Open the instance in the execution view
- Navigate to the Notes panel (right side)
- On the right side of the panel, locate the Execution Comments section
- Type your comment in the rich text editor
- Click Add Comment (or press Ctrl+Enter)
- The comment appears immediately in the comment list and is broadcast to all connected users
Comment Properties
Section titled “Comment Properties”Each execution comment records:
| Property | Description |
|---|---|
| Content | Rich-text HTML body of the comment |
| Author | The user who posted the comment |
| Timestamp | The exact date and time the comment was created |
Immutability
Section titled “Immutability”Once posted, an execution comment cannot be edited or deleted. This design ensures a reliable audit trail of what was communicated during execution. If you need to correct information, post a follow-up comment with the correction.
Permissions
Section titled “Permissions”Adding instance execution comments requires the AddInstanceExecutionComment permission. Available to:
- Instance Head
- Deputy Head
- Executor
- Editor
- Observer (can add comments only)
Step-Level Execution Notes
Section titled “Step-Level Execution Notes”Each individual step also has its own execution note — a single editable rich-text document scoped to that step. Step notes are ideal for documenting step-specific observations that do not belong in the instance-wide note.
Creating and Editing
Section titled “Creating and Editing”- Select the step in the step structure panel
- In the step detail panel, locate the step execution note area
- Click into the editor and write or update the note
- Changes are saved automatically and synchronized in real time
Field Locking
Section titled “Field Locking”Step execution notes use the same field-locking mechanism as instance notes:
- One user at a time can edit a step’s note
- Other users see a lock indicator with the editor’s name
- Lock expires after 30 seconds of inactivity
Permissions
Section titled “Permissions”Editing step execution notes requires the EditStepExecutionNote permission. Available to:
- Instance Head
- Deputy Head
- Executor
Step-Level Execution Comments
Section titled “Step-Level Execution Comments”Each step has its own append-only comment stream, separate from the instance-level comments. Step comments are useful for documenting decisions, issues, or handoff information specific to a single step.
Adding a Step Comment
Section titled “Adding a Step Comment”- Select the step in the step structure panel
- In the step detail panel, locate the step execution comments section
- Type your comment in the editor
- Click Add Comment or press Ctrl+Enter
- The comment is posted and broadcast to all connected users
Properties and Immutability
Section titled “Properties and Immutability”Step execution comments have the same properties as instance comments (content, author, timestamp) and are equally immutable — once posted, they cannot be edited or deleted.
Permissions
Section titled “Permissions”Adding step execution comments requires the AddStepExecutionComment permission. Available to:
- Instance Head
- Deputy Head
- Executor
Execution Log
Section titled “Execution Log”In addition to execution notes and comments, RAMP maintains an Execution Log — a chronological record of both user comments and system-generated action entries.
What Appears in the Execution Log
Section titled “What Appears in the Execution Log”| Entry Type | Description | Visual Style |
|---|---|---|
| User comments | Rich-text messages posted by team members | Standard formatting with author avatar |
| Step actions | System-generated entries for Start, Complete, Pause, Resume, Cancel, Skip, Abort | Monospace font |
| Force actions | Force Complete, Force Skip, Force Abort, Force Cancel | Red background highlight |
Adding Comments via the Execution Log
Section titled “Adding Comments via the Execution Log”- Navigate to the Execution Log tab in the notes panel
- Type your message in the rich text editor at the bottom
- Use the formatting toolbar for bold, italic, headings, lists, code blocks, text color, and highlighting
- Click Add Comment or press Ctrl+Enter
Filtering the Execution Log
Section titled “Filtering the Execution Log”The execution log supports filtering to help you find specific entries:
- Click the Filters button to reveal filter options
- By action type: Show only comments, step started events, completions, etc.
- Force actions only: Isolate force action entries for review
- By date range: Focus on a specific time window
Pagination
Section titled “Pagination”The execution log loads entries in pages of 50. Use the Load More button to view older entries. The pagination indicator shows your current position (e.g., “Page 1 of 3 — 142 total entries”).
Rich Text Formatting
Section titled “Rich Text Formatting”Both notes and comments support rich text formatting through the built-in editor:
| Format | How to Use |
|---|---|
| Bold | Toolbar button or Ctrl+B |
| Italic | Toolbar button or Ctrl+I |
| Headings | Heading dropdown in toolbar |
| Bulleted list | Toolbar button |
| Numbered list | Toolbar button |
| Code block | Toolbar button (monospace formatting) |
| Text color | Color picker in toolbar |
| Text highlight | Highlight picker in toolbar |
Real-Time Synchronization
Section titled “Real-Time Synchronization”All notes and comments are synchronized in real time through SignalR:
- Notes: When one user edits an execution note, the updated content is broadcast to all other users viewing the same instance or step. The field-locking mechanism prevents edit conflicts.
- Comments: New comments appear instantly in all connected browsers. No page refresh is needed.
- Execution log entries: System-generated entries (step started, completed, etc.) and user comments appear in real time.
Notes and Comments on Terminal Instances
Section titled “Notes and Comments on Terminal Instances”When an instance reaches Completed or Cancelled status:
- All execution notes become read-only
- No new execution comments can be added
- Existing notes and comments remain visible for audit and review purposes
- The execution log remains viewable with all filtering options
Best Practices
Section titled “Best Practices”Use Notes for Evolving Information
Section titled “Use Notes for Evolving Information”- Maintain a running status in the instance execution note (e.g., “Currently blocked on Step 3.2 — waiting for vendor response”)
- Use step notes for step-specific known issues or workarounds
- Update notes as the situation changes; notes are meant to reflect the current state
Use Comments for Point-in-Time Records
Section titled “Use Comments for Point-in-Time Records”- Post comments when a decision is made (“Decided to proceed with Option B per John’s recommendation”)
- Document handoffs between shifts (“Shift 2 taking over. Steps 1-4 complete, Step 5 in progress”)
- Record unexpected observations that should be preserved for audit
Leverage the Execution Log
Section titled “Leverage the Execution Log”- Use execution log comments for real-time team communication during active execution
- Filter by force actions when reviewing instances for compliance
- Use date range filters to focus on specific phases of execution