Usage Guide

This document explains how the system is used. For setup see Installation; for technical detail see Architecture.

Who can do what

There are two kinds of users in the system: requesters (no password, no registration) and staff (password login, role-based).

Page	Requester	it_staff	it_manager	admin
Create / track a ticket (public)	✅	✅	✅	✅
Dashboard, ticket management, calendar, tasks	—	✅	✅	✅
Company / location / category / custom field management	—	—	✅	✅
Reports, templates	—	—	✅	✅
Password vault	—	—	✅	✅
Staff management and company assignment	—	—	—	✅

Roles: admin (System Administrator), it_manager (IT Manager), it_staff (IT Staff).

Company scope — the most important concept

Role	What they see
admin	Everything. All companies, including records not tied to any company ("global").
it_manager	Only their assigned companies. A company-specific manager.
it_staff	Only their assigned companies.

Staff are assigned to companies from the Staff Management screen. This can only be done by an admin — company assignment is an authorization decision.

Within their own companies, an it_manager can do the following: ticket management, location/category/custom field definitions, reports, and the password vault. They cannot access the data of a company they aren't authorized for by any route — they cannot move records to that company, nor assign a company to themselves.

Requester — public portal

No login, no registration. The requester only provides their email address.

Creating a ticket — /create

1. Select a company → the locations and categories defined for that company are loaded.
2. Select a category → the SLA times and automatic assignment tied to the category kick in.
3. Company-specific dynamic fields are filled in (text, number, select, phone, URL, email, and long-text types are supported — the admin defines them).
4. Title, description, priority, and optional file attachments (default maximum 25 MB).
5. On submission the ticket receives a number and an unguessable access link.

Status tracking — the access link

The link provided after creation (and in notification emails): https://<site>/ticket/<accessToken>

On this page the requester:

• Sees the ticket's live status (updated instantly via SSE).
• Writes a reply and sends file attachments.
• Reads the IT team's public notes. Internal notes are not shown here.

Past requests — /track

Query by ticket number + email. Alternatively, with just an email, all tickets belonging to that address are listed (rate-limited to 10 requests per minute).

Ticket statuses

Status	Meaning
open	Open — not yet handled
in_progress	In progress
waiting_user_response	Awaiting user response
waiting_other_department	Awaiting support from another department
topic_transferred	Topic transferred
process_outside_it	Process progressing outside IT
on_hold	On hold
resolved	Resolved
closed	Closed

Priorities: low (Low), medium (Medium), high (High), critical (Critical).

IT team — staff panel

Login: /staff/login. The session is managed with a 15-minute access token + a 7-day refresh cookie; closing and reopening the tab preserves the session, and clicking "Log out" genuinely revokes it on the server side.

After logging in, authenticator-based two-factor authentication can be enabled from the Account and Security screen. The setup key is valid for 10 minutes; to enable it, the first 6-digit code produced by the app is verified. On subsequent logins this code is requested after the password.

Dashboard — /staff

Counts of open/in-progress/resolved tickets, SLA status (approaching and breached), and tickets assigned to you.

Ticket management — /staff/tickets

• List: filter by status, priority, company, category, and assignee; free-text search.
• Bulk action: select multiple tickets and change status/assignment.
• Detail (/staff/tickets/:id):
  • Change status and priority, assign to staff.
  • Public reply — visible to the requester, sends an email notification.
  • Internal note — visible only to staff, never shown to the requester.
  • Add files, ticket history (who changed what and when), SLA counter.
  • An onsite support appointment can be created from here.

Onsite support calendar — /staff/onsite

Appointment types: Come to the IT Room, Meeting Room, Onsite Intervention.

When creating an appointment a duration is selected and it is drawn on the calendar in proportion to its actual duration. Because appointments are not assigned to staff, parallel appointments at the same time are normal — the conflict warning has been deliberately removed.

Task management — /staff/tasks

Internal tasks independent of tickets. They can be assigned to multiple people, commented on, and given a due date.

Task statuses: open, in_progress, done, cancelled. Task priorities: low, medium, high, critical — the same as ticket priorities.

On the list screen, tasks can be filtered by assignee, priority, status, and text; they can be sorted by due date, priority, creation, or title. The counter tiles at the top are clickable filter shortcuts (e.g. "Overdue"). Status can be changed directly from the list.

Admin operations

Company management — /staff/companies (admin, it_manager)

• Company: name, group type (call_center, corporate, warehouse, retail), logo, theme color.
• allowedDomains: email domains allowed to open tickets. If empty, there is no restriction.
• portalDomains: which FQDN represents the company. When a user arrives from that domain, the company's logo and color are applied automatically (branding).
• notificationEmail: the IT group mailbox that new tickets land in.
• Locations: address, floor information.
• Categories: hierarchical (subcategories), sortable, with per-category SLA (response and resolution time, in minutes) and automatic assignment.
• Custom fields: company-specific form fields — type, required flag, options.
• Per-company SMTP: each company can send mail with its own SMTP. If not defined, global SMTP is used. A test email can be sent from the panel.

Templates — /staff/templates (admin, it_manager)

• Email templates: ticket created, status changed, assigned, note added, appointment scheduled, SLA warning.
• SMS templates: if an SMS gateway is defined.
• Canned responses: boilerplate texts added with a single click in the ticket detail.

Reports — /staff/reports (admin, it_manager)

Ticket distribution, staff performance, category breakdown, overview, SLA trends, and CSV export.

Staff management — /staff/staff-management (admin only)

Add/edit/delete staff, assign roles, and set company scope. All operations are written to the audit log.

Password vault

/staff/passwords — admin and it_manager.

• admin sees all records.
• it_manager sees only the records of their assigned companies and can add new records only for those companies.
• Records not tied to a company ("global") are visible only to admin. Global records (such as domain admin and root passwords) tend to be cross-company secrets; that is why an it_manager can neither see nor create them.

For storing corporate passwords (servers, licenses, service accounts). They are not hashed, because passwords must be viewable again; instead they are encrypted with AES-256-GCM.

• Only the password and notes are encrypted. Title, category, URL, and username are plain text (so they can be searched).
• The list screen never returns passwords — they are shown masked.
• When "Show" is clicked the password is decrypted on the server, automatically hidden on screen after a few seconds, and every view is written to the audit log.
• Copy to clipboard, search, and filtering are supported.

What to do after the first setup

1. Change the seed passwords. admin123 / staff123 are for the demo. If you ran the seed in production, change them immediately; if you didn't, create the first admin manually.
2. Define your companies — locations, categories, and per-category SLA times.
3. Set up custom fields — decide what extra information each company's ticket form should ask for.
4. Test SMTP — verify global SMTP, define per-company SMTP if needed, and send a test email from the panel. If email doesn't work, requesters cannot receive their access links.
5. Add staff and assign their company scopes — if you don't assign a scope, it_staff will see all companies.
6. Edit the email templates — the defaults work, but review them to match your organization's language.
7. Back up CREDENTIALS_ENC_KEY — if you're going to use the password vault.