Appearance
Running a Design Review
Getting a drawing checked: raising comments against elements, walking each one through the five-state review lifecycle with the right person at each step, and bringing a client's marked-up PDF back in as comments.
The two comment systems
Which comment system you get depends on which editor the drawing is in. They are separate, and they behave differently on purpose.
Draw (/draw) | P&ID models (/admin/pid-models) | |
|---|---|---|
| Panel | Comments drawer, top-right of the canvas | Comments panel, toggled from the toolbar or View → Comments Panel |
| Anchored to | A sheet, or a specific symbol | A drawing's revision, with a canvas marker |
| Statuses | Open / Resolved / Closed | Open → Acknowledged → Resolved → Verified → Closed |
| Role separation | No — anyone can resolve | Yes — each transition belongs to a role |
@mentions | Yes | — |
| Live updates to other viewers | Yes | — |
| Import a marked-up PDF | No | Yes |
For a quick internal check on a drawing you are authoring, the Draw drawer is the right tool — threads, replies, @mentions, live updates. It is documented in full at Comments and Markers.
For a formal design review — one where a checker, a reviewer and an approver each have a distinct job and the record has to show who did which — use the model editor's review comments. That is what the rest of this page is about.
Step 1 — Open the review panel
- Open the model from P&ID models (
/admin/pid-models) and select the drawing you are reviewing from the view tabs in the footer. - Toggle the panel on, either way:
- the Comments button in the toolbar — it carries a red badge with the unresolved count, or
- View → Comments Panel in the menu bar.
The panel opens beside the canvas, and each comment is anchored to the symbol it was raised on.
The panel header reads Comments. It can be collapsed, docked to the panel column, or closed from its header buttons. Comments that are anchored to a position show a marker on the canvas, and the Scroll to location control on a comment takes you to it.
Step 2 — Raise comments
Type into the "Add a comment…" box at the foot of the panel and submit — Ctrl+Enter (or Cmd+Enter) sends without reaching for the mouse. A comment can be replied to, so a question and its answer stay together.
When there are none, the panel says "No comments yet. Add one below."; with a status filter active and nothing matching, it says "No status comments."
Write comments that name the change you want. "Add flow measurement at the inlet — required for consent monitoring" can be acted on and verified; "check this" cannot.
Step 3 — Walk each comment through the lifecycle
A review comment moves through five states, and each transition belongs to a role. The point is separation of duties: one person should not be able to walk a comment from raised to closed alone.
Open ──Acknowledge──► Acknowledged ──Resolve──► Resolved ──Verify──► Verified ──Close──► Closed
▲ │ │
└──────────────────────── Reopen ──────────────────────────────┴──────────────────────────┘| Action | Available when the comment is | Done by | What it means |
|---|---|---|---|
| Acknowledge | Open | Checker | "I have seen this and will address it" |
| Resolve | Acknowledged | Draughtsperson | "Fixed — a checker must verify" |
| Verify | Resolved | Checker | "The resolution is satisfactory" |
| Close | Verified | Approver | Permanently closes the comment |
| Reopen | Verified or Closed (Checker); anything but Open (Approver) | Checker or Approver | Reopens for further discussion |
Only the actions your roles allow are rendered on a comment. If a comment shows no buttons at all, it is waiting on somebody else.
Who holds which role
Your review roles come from your company role. The mapping is deliberately not cumulative:
| Your company role | Review roles you act in |
|---|---|
| Viewer | none — read-only |
| Engineer | draughtsperson |
| Reviewer | checker |
| Approver | approver |
| Project Manager | checker, approver |
| Admin | draughtsperson, checker, approver |
| Owner | draughtsperson, checker, approver |
So an Engineer resolves comments but neither acknowledges nor closes them — that is the design, not a permissions bug. Admin and Owner hold all three, which is the intended exception for a small team or an administrator unblocking a stuck review.
The panel only hides the buttons; the server enforces the same rules regardless, so asking a colleague to click it for you is the answer, not a workaround.
Step 4 — Bring an external reviewer's PDF markup back in
When a client or an external checker returns a marked-up PDF, you do not have to retype their comments.
- In the model editor's toolbar, click Import PDF — its tooltip reads "Import annotated PDF markup as comments".
- The Import PDF Markup wizard runs three steps: Upload PDF → Link Markups → Confirm.
- On Link Markups, each annotation found in the PDF is matched to something on the drawing. You can skip any markup you do not want brought across.
- Give each markup a severity: Comment, Minor, Major or Critical.
- Confirm shows an Import Summary before anything is created.
On Link Markups, each markup row carries its severity picker and a skip control.
The result is ordinary review comments in the panel, carrying the same five-state lifecycle as comments raised in the app.
Step 5 — Put the review in somebody's queue
Comments record the conversation. A workflow records the hand-off: who has to act, and by when.
Start one from a project's page (Start workflow, next to Edit and Duplicate) or from Workflows (/admin/workflows). The three standard templates are:
| Template | Sequence |
|---|---|
| Simple Review | Draft → Human Review → Released |
| Standard Review | Draft → Agent Cross-Review → Human Review → Final Approval → Released |
| Regulatory Approval | Draft → Process Review → Standards Check → Client Review → Regulatory Approval → Released |
Name an assignee when you start it, or the first step stays with you and nobody is told. The step lands in the assignee's Approvals list (/approvals) and in their bell menu, and they pick Approve or Reject with optional comments.
The whole mechanism — installing the standard templates on a new organisation, who gets notified, and why the automated "Draft" and "Agent Cross-Review" steps are skipped rather than run — is documented at Starting a Workflow. Read that before you rely on the longer templates.
The automated checks that run alongside the review
Two things check the drawing without being asked, and both are worth clearing before you send it out for human review:
- The Validation panel — an instant client-side check as you draw plus a deeper server check on save, merged into one list, with a badged issue count on the toolbar button. See Server-Side Validation.
- The project stage gate — per-stage checks on the project as a whole, including whether every drawing is approved and whether comments are resolved. See A Revision Cycle.
Note what is not on this list. There is no automated discipline-by-discipline design critique: ErgoPlanner has four agents you can dispatch — P&ID Designer, Planner, Bill of Materials and Simulation — and none of them is a reviewer. A design review here is people, with the software keeping the record straight.
Things worth knowing
- The two comment systems do not share data. A comment raised in the Draw drawer does not appear in the model editor's panel, and vice versa. Decide which document the review runs against before you start collecting comments.
- Review comments hang off a revision. That is why the lifecycle survives a re-issue: the comments raised against Rev A stay attached to Rev A.
- Comments must be resolved for some stage-gate advances. A comment still Open can block a project from advancing. Clear them, do not delete them.
@mentionsare a Draw-drawer feature. To pull somebody into a model review comment, assign them a workflow step instead.
See also
- Comments and Markers — the Draw page's own comments drawer
- Issuing a Drawing — freeze and send what the review approved
- A Revision Cycle — what happens after the comments come back
- Notifications — where a review request shows up