Roles and Permissions
Control what each user type sees in Planara's responses -- document types, technical detail, and escalation behavior.
What this page does
The Roles page controls what different user types see in Planara's responses. A technician role might see full specs, torque values, and part numbers, while an operator role gets simplified procedures without technical detail.
Core concept
Roles do not control access to the backoffice — that is handled by user access levels. Instead, roles control the content and presentation of Planara's answers in the technician/operator frontend.
When a query comes in, the user's role determines:
- Which document types are included in retrieval
- Whether CKL compliance citations are shown
- Whether part numbers, torque specs, and diagnostic metadata are visible
- What happens when Planara's confidence is too low to give a good answer
Getting started with roles
Load templates
If your workspace has no roles yet, click "Load Templates" to seed pre-configured roles based on your vertical (e.g., marine). Templates include:
- Technician -- full access to all content types, specs, and diagnostic info
- Operator — simplified answers with service escalation prompts
Templates can be customized after loading.
Create custom role
Click "+ Custom Role" and enter a name. The name will be slugified (e.g., "Service Manager" becomes service_manager). A new role is created with default settings that you can then customize.
Test Query panel
When roles exist, a "Test Query" panel appears at the top. This lets you run a query against the live API with a specific role selected, directly from this page. This is invaluable for verifying that role configurations produce the expected output.
- Type a question
- Select a role from the dropdown
- Click "Run"
- See the response, including latency, confidence, active skill, summary text, and full JSON
Role settings
Click on any role to expand its configuration panel.
Document Type Visibility
Toggle which document types are included when this role queries Planara:
| Doc Type | Description |
|---|---|
| Spec Tables | Technical specification tables (dimensions, capacities, torque values) |
| Procedures | Step-by-step maintenance and repair procedures |
| Safety Warnings | DANGER, WARNING, CAUTION, NOTICE labels from manuals |
| Narrative | Descriptive text, theory of operation, background |
| Parts Lists | Part numbers, quantities, exploded diagram references |
| Diagrams | Technical diagrams, schematics, illustrations |
Example: An "owner" role might only have Procedures and Narrative visible, while a "technician" role has all types visible.
Boolean toggles
| Toggle | Description |
|---|---|
| CKL Attribution | Whether compliance citations (blue chips) appear in responses |
| Part Numbers | Whether specific part numbers are included in text |
| Torque Specs | Whether torque specifications are shown |
| Relevance Scores | Whether retrieval confidence scores are shown (debug feature) |
| Skill Indicator | Whether the active skill name is shown in responses |
| Recovery Indicator | Whether the answer recovery activation status is shown (debug feature) |
Confidence Threshold
A number from 0 to 1. When Planara's confidence for a response falls below this threshold, instead of showing a potentially poor answer, it shows the escalation message.
- 0 (default) -- show all responses regardless of confidence
- 0.5 -- hide responses below 50% confidence
- 0.7 -- only show high-confidence responses
Escalation Message
The text shown to the user when Planara's confidence is below the threshold. Example: "Contact your Yamaha dealer for assistance with this question."
This is a critical field for owner-facing roles. When Planara cannot confidently answer, you want owners to contact a qualified dealer rather than rely on a low-confidence answer.
Role actions
| Action | Description |
|---|---|
| Save | Persist configuration changes |
| Cancel | Discard changes |
| Test as (Role) | Opens the technician frontend with this role selected (new tab) |
| Delete | Remove the role. Only available for non-template roles. |
FAQ
Q: What is doc_type_visibility?
A: It controls which types of document content are included in the retrieval step. If "Spec Tables" is not in a role's visibility list, spec table content will be filtered out before the response is generated.
Q: What does "Escalation message" actually do? A: When a user with this role asks a question and Planara's confidence score is below the configured threshold, the response is replaced with this escalation message. For owner roles, this typically directs them to contact their dealer.
Q: Should I enable Relevance Scores and Recovery Indicator for technicians? A: Generally no. These are debug features useful during development. They add noise to the response for everyday use. Enable them temporarily when diagnosing retrieval quality issues.