Getting Started

Welcome to Corejobtrack Desktop, the desktop client for the Corejobtrack task management system. This guide will walk you through installation, logging in, and navigating the application for the first time.

System Requirements

• Operating System: Windows 10+, macOS 11+, or Linux (with desktop environment)
• Network: Internet connection required for initial login and data sync (offline mode available after first login)
• Disk Space: ~100 MB for the application, plus local database storage

Installation

From a Pre-Built Package

1. Download the installer for your platform from your organization's distribution channel.
2. Run the installer:

• Windows: Double-click the .exe file and follow the setup wizard. The application installs to your Program Files directory.
• macOS: Open the .app bundle and drag it to your Applications folder.

1. Launch Corejobtrack Desktop from your applications menu or desktop shortcut.

From Source (Developer Setup)

1. Ensure Python 3.10 or later is installed.
2. Clone the repository and navigate to the project directory.
3. Install dependencies:

   pip install -r requirements.txt

1. Copy the environment template and configure it:

   cp .env.sample .env

1. Edit .env to set your server URL and other options (see Configuration below).
2. Run the application:

   python main.py

Configuration

The .env file controls how the application connects to your server. Key settings:

Most users will only need to set SERVER_URL if connecting to a different server.

Logging In

When you launch Corejobtrack Desktop, the login screen appears.

Login Screen Layout

• Logo at the top — displays your organization's branding
• Username field — enter your email address or username
• Password field — enter your password
• Save password checkbox — stores your credentials securely in your operating system's keychain (macOS Keychain, Windows Credential Manager)
• Auto-login checkbox — automatically logs you in on the next app launch (requires saved password)
• Log In button — submits your credentials

Connection Status

At the bottom of the login screen, you will see:

• A colored dot indicating server connectivity:
• Green — connected to server
• Orange — slow connection detected
• Red — cannot reach the server
• Server version and App version labels for reference

Logging In Step by Step

1. Enter your username or email in the first field.
2. Enter your password in the second field.
3. Optionally check Save password to remember your credentials.
4. Optionally check Auto-login to skip the login screen next time.
5. Click Log In or press Enter.

If your credentials are correct, the login window closes and the main application window opens. If login fails, an error message appears in red text below the login button.

Rate Limiting

For security, after 5 failed login attempts within 5 minutes, login is temporarily locked. A message will tell you how many seconds remain before you can try again.

Auto-Login

If you previously checked Save password and Auto-login, the application will attempt to log you in automatically when launched. If the server is unreachable or your credentials have changed, you will be returned to the login screen.

After manually logging out, auto-login is suppressed for the next launch so you can log in with different credentials if needed.

First Look: The Main Window

After logging in, the main application window opens with several key areas:

Header Bar

The header bar runs across the top of the window and contains:

• Logo (far left) — your organization's branding
• Navigation tabs (center) — buttons to switch between views:
• Home (house icon) — your active inbox
• Completed — archived/completed items
• Customers — customer database
• Contacts — contact directory
• Equipment — equipment registry
• Vendors — vendor directory
• Templates — work item templates
• Action buttons (far right):
• Notification badge — shows unread notification count (hidden when zero)
• Theme toggle — sun/moon icon to switch between light and dark mode
• Settings — your profile picture (or gear icon); click for a dropdown menu
• Logout — red-bordered button to sign out

Content Area

The large area below the header shows the currently selected view. By default, you start on the Home (Inbox) view, which displays all your active work items.

Status Bar

At the very bottom of the window:

• Left: Connection indicator (colored dot) and pending sync count
• Center: Record count for the current view
• Right: App and server version numbers

Menu Bar

The traditional menu bar at the top of the window provides additional options:

• File — Refresh (Ctrl+R), Logout, Quit (Ctrl+Q)
• Edit — Create new Task (Ctrl+N), Service Ticket (Ctrl+Shift+N), or Support Ticket (Ctrl+Alt+N)
• View — Navigate to any view with keyboard shortcuts (Ctrl+1 through Ctrl+9), change theme
• Database — Quick links to Customers, Contacts, Equipment, Vendors
• Resources — Open web links to Portal, File Access, Wiki, Calendar, Mail, and more
• Help — About dialog and documentation link

System Tray

On supported systems, a Corejobtrack icon appears in your system tray. Right-click it for options to show the window or quit. Left-click to bring the window to the foreground. New notifications will appear as system tray popups.

Keyboard Shortcuts Quick Reference

What's Next

Now that you are logged in and familiar with the layout, explore the following guides:

• Inbox & Navigation — managing your active work items
• Tasks — creating and managing tasks with checklists
• Service Tickets — field service work with time tracking
• Support Tickets — customer support with communication logs
• Customers — managing your customer database
• Settings & Preferences — customizing your experience

Inbox & Navigation

The Inbox is your home screen in Corejobtrack Desktop. It shows all of your active work items — tasks, service tickets, and support tickets — in a single unified list. From here, you can search, filter, sort, and open any item.

Overview

When you click the Home button (house icon) in the header bar or press Ctrl+1, the Inbox view loads. It fetches your active work items from the server and displays them as a scrollable list of cards.

Toolbar

The toolbar at the top of the Inbox provides controls for finding and organizing your items.

Search

The search field (placeholder: "Search tickets...") filters items in real time as you type. It searches across:

• Title
• Ticket number or task code
• Description

There is a 300-millisecond delay after you stop typing before the filter applies, so the list does not jump around while you are still entering text. Press Enter to search immediately. Click the X button inside the search field to clear your search.

Sort Field

The sort dropdown lets you choose how items are ordered. Options include:

• Date Modified — when the item was last changed
• Date Created — when the item was first created
• Title — alphabetical by title
• Type — grouped by item type (task, service ticket, support ticket)
• Urgency — by priority level (Critical first, then High, Medium, Low)
• Ticket # — by ticket or task code number
• Due Date — by upcoming deadlines
• Assigned To — by assignee name

Your sort preference is saved and restored across sessions.

Sort Direction

The arrow button next to the sort dropdown toggles between descending (↓) and ascending (↑) order. Click it to reverse the current sort. This preference is also saved.

Refresh

The circular arrow button (⟳) reloads your items from the server. The button is disabled while loading. You can also press Ctrl+R to refresh.

+ New Button

The bright blue + New button creates new work items. It pulses with a subtle glow animation to draw attention. Click it to reveal a dropdown menu:

• New Task — creates a blank task
• New Service Ticket — creates a blank service ticket
• New Support Ticket — creates a blank support ticket
• From Template... — opens a dialog to select a saved template, which pre-fills the title, description, color, type, and steps

Type Filter Tabs

Below the toolbar, four tabs filter items by type:

Click a tab to instantly filter the list. The search and sort settings still apply on top of the type filter.

Item Cards

Each work item appears as a card in the list. Cards are richly detailed so you can quickly scan your inbox without opening individual items.

Card Layout

Each card contains the following information (left to right, top to bottom):

Unread Indicator

A blue dot (●) appears on the left edge of items you have not yet viewed.

Color Bar

A thin vertical color strip on the left edge. The color comes from the item's assigned color tag and helps you visually categorize items at a glance.

Row 1: Title and Badges

• The item title in bold text (highlighted if matching your search)
• Task type badge — a colored chip showing the task type (e.g., "Installation", "Repair") if one is assigned
• Signature status chip (service tickets only) — shows "Signed", "Signature Pending", "Waiting for Signature", or "Declined"
• Item type chip — gray for Tasks, blue for Service Tickets, purple for Support Tickets

Row 2: Code, Status, and Urgency

• Ticket number or task code in secondary text
• Status label (e.g., "Open", "Paused", "Pending")
• Urgency chip — shown only for High (orange) or Critical (pink) items

Row 2b: Equipment Info (if applicable)

• Equipment name and problem description
• Shows "+N more" if multiple equipment entries are linked

Row 3: Metadata

• Created date and creator on the left
• Emoji indicators on the right:
• 📎 if the item has attachments
• 🌴 if the urgency is Low
• Modified date and modifier
• Due date chip with color-coded urgency:
• Red "Very Late" or "Past Due" for overdue items
• Orange "Due Today" or "Due Tomorrow"
• Yellow for future due dates

Opening an Item

Double-click any card to open its detail view. The detail view replaces the inbox content and shows a Back button to return.

Right-Click Context Menu

Right-click any card to see a context menu with quick actions. The available options depend on the item type:

Tasks

• View — open the task detail view
• Mark Complete — mark the task as completed (with confirmation)
• Archive — move to the archive (with confirmation)
• Delete — permanently delete (with warning: "This action cannot be undone")

Service Tickets

• View — open the detail view
• Mark Complete — complete the ticket (with confirmation)
• Clone Ticket — create a copy of the ticket (with confirmation)
• Archive — move to archive (with confirmation)
• Delete — permanently delete (with warning)

Support Tickets

• View — open the detail view
• Mark Complete — complete the ticket (with confirmation)
• Archive — move to archive (with confirmation)
• Delete — permanently delete (with warning)

Empty State

If no items match your current filter and search criteria, a centered message appears: "No items to display."

Record Count

The status bar at the bottom of the window shows the total number of items currently displayed (e.g., "42 items").

Tips

• Use the type filter tabs combined with sort by Urgency to quickly find your most critical items.
• The search field is great for finding a specific ticket by number — just type the ticket code.
• Right-click for quick actions without opening the full detail view.
• Items with a blue dot are unread — you haven't viewed them yet.
• Check the due date chips for color-coded deadline urgency at a glance.

Tasks

Tasks are the simplest work item type in Corejobtrack. They are ideal for general to-do items, internal assignments, and work that does not require the specialized fields of service or support tickets. Tasks support checklists (steps), notes, customer information, and private team chat.

Creating a Task

There are several ways to create a new task:

1. Click the + New button in the Inbox toolbar and select New Task.
2. Use the menu: Edit > New Task.
3. Press Ctrl+N.
4. Select From Template... in the + New menu to create a task pre-filled from a saved template.

A new task detail view opens with empty fields ready to fill in.

Task Detail View

The task detail view is where you create, view, and edit tasks. It has a header section with form fields at the top and a tabbed area below for steps, notes, customer info, and chat.

Header

• Back button (< Back) — returns to the Inbox
• Title — shows "New Task" for new items or "Task: [code]" for existing ones
• Save button — saves all changes to the server (shows "Saving..." while in progress)

Form Fields

Title (required)

A single-line text field for the task name. This is the only required field — you must enter a title before saving.

Description

A multi-line text area for detailed information about the task.

Status

A dropdown to set the task's current state:

• Open — actively being worked on
• Paused — temporarily on hold
• Completed — finished

Urgency

A dropdown to set the priority level:

• Low — no rush
• Medium — normal priority (default)
• High — needs prompt attention
• Critical — highest priority, urgent

Due Date

Check the Set due date checkbox to enable the date picker. Select a date from the calendar popup. Uncheck the box to clear the due date.

Steps Tab

The Steps tab provides a checklist for breaking a task into smaller items.

Adding Steps

1. Type a step description in the text field (placeholder: "New step description...").
2. Click Add Step or press Enter.
3. The step appears in the list below.

Using the Checklist

Each step has a checkbox next to it:

• Check the box to mark the step as completed. The text will appear with strikethrough styling.
• Uncheck the box to reopen the step.

For saved tasks, checking or unchecking a step immediately updates the server. For new (unsaved) tasks, steps are saved when you click Save.

Steps are displayed in the order they were added.

Notes Tab

The Notes tab provides a running log of comments and updates on the task.

Viewing Notes

Existing notes appear in a list, each showing:

• The author's name in brackets
• The timestamp
• The note text below

Notes are displayed in chronological order.

Adding a Note

1. Type your note in the text area at the bottom (placeholder: "Write a note...").
2. Click Add Note.
3. The note is immediately posted to the server and appears in the list.

Notes cannot be edited after posting. They serve as a permanent record of communication about the task.

Customer Tab

The Customer tab lets you associate a customer and contact person with the task.

Customer Information Fields

• Customer Name — the business or company name
• Address Line 1 — street address
• Address Line 2 — suite, unit, or additional address info
• City, State, ZIP — location fields in a single row

Contact Information Fields

• Contact Name — the person's name
• Phone — phone number
• Email — email address

All customer and contact fields are optional and save with the task.

Private Chat Tab

The Private Chat tab provides a real-time messaging area for internal team communication about the task. This tab only appears for existing (saved) tasks — not for new tasks that have not yet been saved.

For detailed information about using private chat, see the Private Chat guide.

Saving

Online

When you click Save:

• New tasks are created on the server. The title becomes "Task: [new code]" and additional tabs (like Private Chat) become available.
• Existing tasks are updated with your changes.

Offline

If you are offline when you save:

• Your changes are queued in the local outbox.
• A dialog confirms: "You are offline. Changes have been queued and will sync when connected."
• When connectivity returns, the sync service automatically sends your changes to the server.

For more about offline behavior, see the Offline Mode & Sync guide.

Tips

• Break complex tasks into steps to track progress on sub-items without creating separate tickets.
• Use notes to document decisions, updates, and handoffs — they create a permanent audit trail.
• Templates save time for recurring tasks. Create a template with predefined steps and description, then use "From Template..." to create new tasks instantly.
• The urgency and due date fields drive the color-coded indicators in the Inbox, helping your team prioritize at a glance.

Service Tickets

Service tickets are designed for field service work — on-site repairs, installations, deliveries, and dispatched jobs. They include specialized fields for dispatch information, equipment tracking, time entries, customer signatures, and file attachments.

Creating a Service Ticket

There are several ways to create a new service ticket:

1. Click + New in the Inbox toolbar and select New Service Ticket.
2. Use the menu: Edit > New Service Ticket.
3. Press Ctrl+Shift+N.

Detail View Overview

The service ticket detail view uses collapsible sections to organize a large amount of information. Each section has a header you can click to expand or collapse it. When collapsed, a brief summary line shows key details so you can see important information at a glance.

Your expand/collapse preferences are remembered across sessions.

Header

• Back button (< Back) — returns to the Inbox
• Title — shows "New Service Ticket" or "Service Ticket: [ticket number]"
• Complete button (checkmark) — marks the ticket as complete and archives it
• Save button (disk icon) — saves all changes

Service Ticket Section

This section contains the core ticket information.

Title

A single-line text field for the ticket title or summary.

Description

A resizable multi-line text area. You can drag the bottom edge of the description field to make it taller or shorter (minimum 60px, maximum 600px). This is useful when working with long descriptions.

Dispatch Information Section

This section tracks dispatch logistics and status.

Read-Only Fields

Ticket ID

The system-generated ticket identifier. Click the clipboard icon (📋) next to it to copy the ID to your clipboard.

Editable Fields

Dispatch #

An external dispatch reference number from your dispatch system.

Customer PO

The customer's purchase order number.

Status

Dropdown with service-specific statuses:

• Pending
• In Progress
• Awaiting Parts
• On Hold
• Ready for Dispatch
• In Transit
• Completed

Dispatch Type

Dropdown for the type of dispatch (e.g., Normal, Scheduled, Warranty, Installation, Training/Contract, Delivery).

Urgency

Priority level: Low, Medium, High, or Emergency.

Equipment/Dispatch Flags

Four checkboxes for logistical requirements:

• Liftgate — a liftgate is required for delivery
• Sprinter — a sprinter van is needed
• Remote — this is a remote service call (no on-site visit)
• Phone Call — a phone call is required

Resolution Section

Track whether and how the ticket was resolved.

• Resolved — check this box when the issue is resolved
• Resolution Notes — a text area describing the resolution, fix applied, or outcome

When collapsed, the summary shows "Resolved" or "Unresolved" along with the first 60 characters of your resolution notes.

Time Tracking Section

The time tracking section logs work sessions and calculates billable hours.

Adding a Time Entry

Click + Add Time Entry to open the time entry dialog. See Time Entry Dialog below for details.

Time Entry Cards

Each logged time entry appears as a card showing:

• Type badge — color-coded label (On-Site, Remote, Travel, Diagnostic, Repair, Installation)
• Calculated time — hours displayed in "Xh Ym" format, automatically rounded to the nearest quarter hour
• Lunch emoji (🍔) — appears if lunch was deducted, with a tooltip showing the deduction amount
• After-hours emoji (🌙) — appears if any time falls outside business hours (Mon–Fri, 8 AM – 5 PM), with tooltip
• Edit button (pencil icon) — reopens the time entry dialog to modify the entry
• Delete button (X) — removes the time entry
• Date range — start and end times in friendly format
• Services performed — description of work done
• Notes — additional notes in italic
• Technician count — if more than one technician, shows count and initials (e.g., "2 technicians (JD/SM)")

Totals

At the bottom of the time section:

• Total Time — sum of all billable hours across all entries
• After-Hours Total — shown separately if any entries include after-hours work

Time Entry Dialog

The time entry dialog captures all details for a work session.

Entry Type

Dropdown: On-Site, Remote, Travel, Diagnostic, Repair, or Installation.

Start Time / End Time / Duration

Three linked fields that auto-sync:

• Change the start time → end time adjusts based on duration
• Change the end time → duration recalculates
• Change the duration → end time adjusts based on start

Duration is in quarter-hour increments (0.25 hour steps).

Lunch Deduction

Dropdown: None, 15 min, 30 min, 45 min, 1 hr, 1 hr 15 min, or 1 hr 30 min.

Timezone

Displays your current timezone with a globe emoji. Hover for the full timezone identifier.

Technicians

A grid of toggle buttons — one per team member. Select all technicians who worked on this session. Selected technicians appear as initials below the grid (e.g., "Selected: JS/SM"). Multiple selections are allowed.

Services Performed

A text area to describe the work done during this session.

Notes

A text area for additional notes about the time entry.

Click Save (or Add for new entries) to confirm, or Cancel to discard.

Customer Section

Associates a customer with the ticket.

• Customer Name — business/company name
• Customer Number/ID — internal account number
• Address Line 1, Address Line 2 — street address
• City, State, ZIP — location fields
• Remove Customer button — clears all customer fields

Contact Section

Associates a contact person with the ticket.

• First Name, Last Name
• Phone, Email
• Contact Preference — dropdown: Phone, Email, Text, or Any
• Remove Contact button — clears all contact fields

Equipment Section

Tracks equipment involved in the service call.

Adding Equipment

Fill in the fields in the "Add Equipment" form:

• Name — equipment make and model
• Serial — serial number
• Problem — description of the issue
• Work Performed — what was done to fix or service it

Click + Add Equipment to add the entry. Multiple equipment items can be added.

Equipment Cards

Each entry shows:

• Equipment name in bold
• Serial number
• Problem description
• Work performed
• A delete button (×) to remove the entry

Counts Section

If equipment entries are linked to customer equipment records (with an equipment ID), a Counts section appears. This is used for tracking machine counts (meters, impressions, etc.).

For each linked piece of equipment:

• Current Count — the most recent recorded value
• Recorded Date — when the count was last taken (yellow warning if older than 1 week)
• New Count — input field to enter a new reading
• Save button — records the new count

Task Sharing Section

Controls who can see the ticket.

• Public checkbox — "Public (visible to all users)" — when checked, all users can see the ticket
• When collapsed, shows "Public" or "Private" with the number of assigned users and teams

Private Chat Section

An embedded chat widget for internal team discussion about this ticket. Only visible for saved (existing) tickets.

See the Private Chat guide for details.

Attachments Section

Upload and manage files associated with the ticket.

Uploading Files

Click + Upload to open a file dialog and select a file. The upload button is only available after the ticket has been saved.

Viewing Attachments

Attachments are displayed in two groups:

Media files (images and videos) appear in a 3-column grid with:

• Large thumbnail preview (200×150px)
• Filename, file type, size, date, and uploader
• Download and delete buttons

Document files (PDFs, spreadsheets, etc.) appear in a compact list with:

• File type icon
• Filename and metadata
• Download and delete buttons

Attachment Gallery

Click a media thumbnail to open the full-screen Attachment Gallery viewer. In the gallery:

• Navigate with the left/right arrow buttons or arrow keys
• See the filename, file counter (e.g., "3/7"), file size, date, and uploader
• Click Download (↓) to save the file
• Click Delete (✕) to remove the attachment
• Press Esc to close the gallery
• For videos, click to download and open with your system's default player

Download All

Click Download All to save every attachment to a folder you choose.

Customer Signature Section

If a customer signature has been collected (via the web portal or mobile app), this section displays:

• Status — color-coded badge: "Signed", "Declined", etc.
• Signed By — the name of the person who signed
• Signed — the date and time of the signature
• Collected By — the technician who collected the signature
• Safety Covers — whether safety covers were confirmed (Yes/No), with notes if "No"

This section is read-only and only appears when signature data exists.

Actions Section

Quick action buttons at the bottom of the detail view:

• Mark Complete (blue) — marks the ticket as complete and archives it
• Clone Ticket (orange) — creates a duplicate of the ticket
• Archive (gray) — moves the ticket to the archive without completing it
• Delete (red) — permanently deletes the ticket

Admin-only:

• View Ticket Log — shows the full change history with timestamps, users, and actions

All destructive actions prompt for confirmation before proceeding.

Tips

• Use the time entry dialog's three-way sync between start, end, and duration — change whichever is most convenient and the others will update automatically.
• After-hours time is automatically detected based on business hours (Mon–Fri, 8 AM – 5 PM). The moon emoji makes these entries easy to spot.
• Clone Ticket is great for recurring service calls to the same customer — it copies all fields so you only need to update what changed.
• Remember to check the equipment flags (Liftgate, Sprinter, Remote, Phone Call) so dispatch knows what resources are needed.
• Upload photos of equipment, work performed, or site conditions to the Attachments section for documentation.

Support Tickets

Support tickets are designed for customer support and communication-focused work. They feature a real-time communication log for team messaging, a ticket change log for audit history, customer contact management, and private team chat.

Creating a Support Ticket

There are several ways to create a new support ticket:

1. Click + New in the Inbox toolbar and select New Support Ticket.
2. Use the menu: Edit > New Support Ticket.
3. Press Ctrl+Alt+N.

Detail View Overview

The support ticket detail view uses a tabbed interface to organize information across five tabs: Communication, Ticket Log, Customer/Contact, Notes, and Private Chat.

Header

• Back button (< Back) — returns to the Inbox
• Title — shows "New Support Ticket" or "Support: [ticket number]"
• Save button — saves all changes (shows "Saving..." while in progress)

Form Fields

The form fields above the tabs capture the ticket's core information.

Title (required)

A single-line text field for the ticket subject. You must enter a title before saving.

Description

A multi-line text area for detailed information about the support request. Maximum height of 100px.

Status

Dropdown for the ticket's current state:

• Open — actively being handled
• Paused — temporarily on hold
• Completed — resolved and finished

Urgency

Priority level: Low, Medium, High, or Critical.

Total Time (hrs)

A numeric field to manually track the total hours spent on this ticket. Enter a decimal value (e.g., "2.5" for two and a half hours).

Communication Tab

The Communication tab is the primary workspace for support tickets. It provides a threaded message log for communicating with your team about the ticket.

Message History

All messages appear in a scrollable list, each showing:

• Author name in brackets
• Timestamp
• Message text

The list automatically scrolls to the newest message.

Sending Messages

1. Type your message in the text area at the bottom (placeholder: "Type a message...").
2. Click Send to post the message.
3. The message is immediately sent to the server and appears in the log.

Typing Indicator

When another team member is typing a message, you will see an indicator below the message list:

• "Someone is typing..." (one person)
• "N people are typing..." (multiple people)

The typing indicator updates in real time.

Ticket Log Tab

The Ticket Log tab shows the complete change history of the ticket. This is a read-only audit trail that records every modification.

Each log entry displays:

• User who made the change
• Timestamp of the change
• Action or description of what changed

This log is automatically maintained by the server — you do not need to add entries manually.

Customer/Contact Tab

The Customer/Contact tab holds all customer and contact person information.

Customer Fields

• Customer Name — the business or company name
• Address Line 1 — street address
• Address Line 2 — additional address info
• City, State, ZIP — location fields in a single row

Contact Fields

All in a single row:

• First Name, Last Name
• Phone, Email

All fields are optional. Empty fields are not sent to the server.

Notes Tab

The Notes tab manages public-facing notes for the ticket.

Public Notes

A multi-line text area for notes that may be visible to the customer (depending on your organization's configuration). This is separate from the private team chat.

Private Chat Tab

The Private Chat tab provides an internal messaging space for your team to discuss the ticket privately. This tab only appears for saved (existing) tickets.

For detailed information about using private chat, including message formatting, typing indicators, read receipts, and more, see the Private Chat guide.

Saving

Online

When you click Save:

• New tickets are created on the server. The title updates to show the assigned ticket number.
• Existing tickets are updated with your changes.
• All tabs refresh to show the latest data.

Offline

If you are offline:

• Changes are queued in the local outbox.
• A confirmation dialog tells you the changes will sync when connectivity returns.

Tips

• The Communication tab is the heart of support ticket workflow — use it to document all interactions and keep your team informed.
• Typing indicators help prevent duplicate responses — if you see someone else is already typing, wait to see their message before composing your own.
• Use the Ticket Log to understand the full history of a ticket, especially when picking up work started by a colleague.
• Public Notes are useful for summarizing the resolution or adding customer-visible information.
• Private Chat is for internal team discussion that should not be visible to the customer.

Customers

The Customers view is a comprehensive customer relationship management (CRM) system built into Corejobtrack Desktop. It lets you browse, search, and manage customer records including company information, contacts, equipment, marketing data, and business profiles.

Accessing Customers

Navigate to the Customers view by:

• Clicking Customers in the header bar
• Pressing Ctrl+3
• Using the menu: Database > Customers

Customer List

The customer list displays all your customer records as rich cards with key information visible at a glance.

Toolbar

Search

Type in the search field (placeholder: "Search customers...") to filter by company name, city, state, phone, email, industry, or parent company. Search results update in real time with a 300ms delay.

Sort Field

Choose how to sort the list:

• Company Name (default)
• City
• State
• Status
• Industry
• Priority

Sort Direction

Toggle between ascending (↑) and descending (↓) order. Your preference is saved.

Refresh

Click the refresh button (↻) to reload customer data from the server.

Customer Cards

Each customer appears as a card showing:

Row 1: Company Name + Status

• The company name in bold
• A status chip: green "Active" or red for other statuses (Inactive, Prospect)

Row 2: Address

• Full formatted address (line 1, line 2, city, state, ZIP)

Row 3: Contact Information

• 📞 Phone number (green)
• 📧 Email address (blue)
• 🌐 Website (teal)
• Fields are hidden if not set

Row 3.5: Profile Chips

• Industry tag (gray chip)
• Priority tag: A (green), B (yellow), C (gray)

Row 4: Count Badges

• 👤 Number of contacts
• 🔧 Number of equipment entries

Opening a Customer

Double-click a customer card to open the detail view. You can also right-click for a context menu with View/Edit and Delete options.

Infinite Scroll

The customer list loads records in batches of 100. As you scroll near the bottom, the next batch loads automatically. The status bar shows your progress (e.g., "150 of 300+ customers").

Customer Detail View

The customer detail view has five tabs that organize all customer data.

Header

• Back button (← Back) — returns to the customer list
• Title — "Customer: [Company Name]"
• Save button — saves changes across all tabs

Tab 1: Company Info

Basic company and address information.

Company Information (Left Column)

• Company (required) — the business name. This is the only required field.
• Phone — main phone number
• Email — main email address
• Website — company website URL
• Account Status — dropdown: Active, Inactive, or Prospect

Shipping Address (Right Column)

• Address 1 — street address
• Address 2 — suite, unit, etc.
• City, State, ZIP

Tab 2: Profile

Detailed company demographics and product information.

Company Demographics

• Industry / Vertical — dropdown with preset choices (click Edit to manage the preset list)
• Company Size — dropdown: 1-10, 11-50, 51-200, 200+
• Annual Revenue Range — dropdown: <$1M, $1-5M, $5-25M, $25M+
• Years in Business — numeric field
• Number of Locations — numeric field
• Geographic Market — dropdown: Local, Regional, National, International
• Union Shop — checkbox
• Parent Company — text field

Products & Equipment

• Key Products/Services — multi-line text area for what the company makes or does
• Equipment Types Used — dropdown with preset choices (click Edit to manage the list)

Tab 3: Marketing

CRM and sales tracking information.

CRM & Tracking

• Lead Source — dropdown with preset choices (click Edit to manage)
• Customer Since — date picker
• Last Contact Date — date picker
• Next Follow-up Date — date picker
• Account Priority — dropdown: A, B, or C
• Buying Cycle — dropdown: Quarterly, Annual, As-needed, Capital planning
• Assigned Sales Rep — dropdown populated with users from the Sales and Administration teams
• Communication Preference — dropdown: Email, Phone, In-person
• Marketing Opt-in — checkbox

Competitive Intelligence & Notes

• Current Pain Points — multi-line text area
• Competitor Equipment — multi-line text area
• Notes — multi-line text area for general notes

Tab 4: Contacts

Manage the people associated with this customer.

Contact List

Each contact appears as a card with:

• Colored avatar with initials
• Full name in bold
• Title (e.g., "Sales Manager", "VP of Operations")
• 📞 Phone number
• 📧 Email address
• ⭐ "Primary" badge for the primary contact

Managing Contacts

Add Contact

Click the Add Contact button to open a dialog with fields for:

• First Name, Last Name, Title, Phone, Email

Edit Contact

Select a contact and click Edit, or double-click the contact card.

Delete Contact

Select a contact and click Delete. A confirmation dialog appears before deletion.

Send Password Reset

Select a contact and click Send Password Reset to send a password reset email to the contact's email address (for portal access). A confirmation dialog shows the contact's name and email before sending.

Right-Click Menu

Right-click a contact for quick access to Add, Edit, Password Reset, and Delete actions.

Tab 5: Equipment

Track the equipment associated with this customer.

Equipment List

Each equipment entry shows:

• 🔧 Equipment icon
• Make and Model (or "(No make/model)" if not set)
• Serial number (S/N)
• Notes preview (first 60 characters, full text in tooltip)
• Quantity badge (if count > 1)

Managing Equipment

Add Equipment

Click Add Equipment to open a dialog with fields for:

• Make, Model, Serial #, Count, Notes

Edit Equipment

Select equipment and click Edit, or double-click the card. The edit dialog includes additional features:

• All standard fields (Make, Model, Serial #, Notes)
• Current Count — displayed as read-only
• Count History — a table showing all recorded counts with date, value, notes, and who recorded it
• New Reading — enter a new count value and optional notes, then click Add Reading to record it

Delete Equipment

Select equipment and click Delete with confirmation.

Saving

Click the Save button in the header to save changes across all tabs. The company name is required — you will see a validation warning if it is empty.

Note: Creating new customers from the desktop client is not currently supported. New customers should be created from the admin web interface. Existing customers can be fully edited.

Tips

• Use Account Priority (A/B/C) combined with sort by Priority in the list to quickly focus on your most important customers.
• The Edit button next to dropdown fields (Industry, Equipment Types, Lead Source) lets you customize the available options for your team.
• Equipment counts are useful for tracking machine meters or inventory. Use the count history to see trends over time.
• Set Next Follow-up Date to keep track of when you need to reach out to a customer again.
• The Primary contact badge helps team members quickly identify the main point of contact.

Contacts, Equipment & Vendors

In addition to the customer-specific contacts and equipment managed within each customer record, Corejobtrack Desktop provides three standalone directory views: Contacts, Equipment, and Vendors. These global views let you browse and manage all records across all customers from a single location.

Contacts Directory

Accessing

• Click Contacts in the header bar
• Press Ctrl+4
• Use the menu: Database > Contacts

Overview

The Contacts directory shows all customer contacts across your entire organization in a searchable, sortable list. This is useful when you need to find a contact but do not know which customer they belong to.

Features

• Search — filter contacts by name, phone, email, or title
• Sort — order by name, company, or other fields
• Contact Cards — each card shows the contact's name, title, company, phone, and email
• Double-click — opens the contact detail view
• Right-click — context menu with edit and delete options

Contact Detail View

The contact detail view shows:

• Full name, title, phone, email
• Associated customer information
• Option to edit or delete the contact

Equipment Directory

Accessing

• Click Equipment in the header bar
• Press Ctrl+5
• Use the menu: Database > Equipment

Overview

The Equipment directory shows all equipment records across all customers. This is useful for looking up a machine by serial number or finding all equipment of a certain make/model.

Features

• Search — filter equipment by make, model, serial number, or notes
• Sort — order by make/model, customer, serial number, or other fields
• Equipment Cards — each card shows make/model, serial number, notes preview, and quantity
• Double-click — opens the equipment detail view
• Right-click — context menu with edit and delete options

Equipment Detail View

The equipment detail view shows:

• Make, model, serial number
• Associated customer
• Count/quantity information
• Count history with timestamps
• Notes

Vendors

Accessing

• Click Vendors in the header bar
• Press Ctrl+6
• Use the menu: Database > Vendors

Overview

The Vendors view manages your vendor and supplier relationships. Vendors are separate from customers and have their own contact lists.

Vendor List

The vendor list uses the same card-based layout as other directories:

• Search — filter vendors by name or other fields
• Sort — order by name or other criteria
• Refresh — reload data from the server
• Infinite scroll — loads more vendors as you scroll down

Vendor Detail View

Double-click a vendor to open the detail view, which includes:

Vendor Information

• Company name
• Address fields (line 1, line 2, city, state, ZIP)
• Phone, email, website
• Account status

Vendor Contacts

Similar to customer contacts, each vendor can have associated contact people:

• Add, edit, and delete vendor contacts
• Each contact has: first name, last name, title, phone, email
• Reorder contacts using the interface

Creating and Managing Vendors

• Create — add new vendors directly from the desktop client
• Edit — modify vendor details and save
• Delete — remove vendors with confirmation

Tips

• Use the Contacts directory when you know a person's name but not their company — it searches across all customers.
• The Equipment directory is great for looking up machines by serial number during service calls.
• Vendor contacts help track your supplier relationships and keep contact information organized alongside your customer data.
• All three directories support the same search, sort, and infinite scroll patterns used throughout the application.

Notifications

Corejobtrack Desktop keeps you informed about changes to your work items through a real-time notification system. Notifications appear as system tray popups, badge counts in the header, and in the dedicated Notification Center.

Accessing Notifications

• Click the notification badge in the header bar (shows unread count when > 0)
• Click the Settings button (profile picture) and select Notifications from the dropdown
• Press Ctrl+8

Notification Center

The Notification Center has two tabs: Activity and System.

Activity Tab

The Activity tab shows server notifications — updates from your team and changes to work items you are involved with.

Notification Format

Each notification displays:

• Title — what happened (e.g., "Task Updated", "New Comment")
• Relative time — how long ago it occurred (in parentheses)
• Message — additional detail about the change

Visual Indicators

• Unread notifications appear in normal text color
• Read notifications appear in gray text

Unread Count

The tab label dynamically shows the number of unread notifications (e.g., "Activity (3)"). When all notifications are read, it simply shows "Activity".

System Tab

The System tab shows local events related to connectivity and sync:

• Network connectivity changes (online, offline, slow connection)
• Sync service events (sync completed, sync failed)
• Other system-level messages

System notifications are added with the newest at the top.

Managing Notifications

Mark All as Read

Click the Mark All Read button in the Notification Center header to mark all notifications as read at once. This clears the unread count and resets the notification badge.

Mark Individual as Read

Right-click a notification in the Activity tab and select Mark as Read. This option only appears for unread notifications.

Delete a Notification

Right-click a notification and select Delete to permanently remove it.

Notification Badge

The header bar displays a red badge with a number next to the theme toggle button. This shows the total number of unread notifications. The badge is hidden when there are no unread notifications.

System Tray Notifications

When new notifications arrive while the application is running, they appear as system tray popup messages (toast notifications). These work even when the application window is minimized.

• Work item notifications display for 5 seconds
• System event notifications display for 3 seconds

On Windows, native toast notifications are used when available, with a fallback to the system tray balloon.

Adaptive Polling

The notification system automatically adjusts how often it checks for new notifications based on your activity level:

This adaptive system ensures you get timely notifications when actively working while reducing server load when you step away.

Error Handling

If the server is temporarily unreachable, the polling system uses exponential backoff — it gradually increases the wait time between attempts (up to a maximum of 2 minutes) to avoid overwhelming the server. Normal polling resumes automatically when the server becomes available again.

If the server returns a rate limit response, polling pauses for the duration specified by the server (typically 60 seconds).

Tips

• Keep an eye on the notification badge in the header — it is the quickest way to know something needs your attention.
• Use Mark All Read after reviewing your notifications to reset the badge.
• The System tab is helpful for diagnosing connectivity issues — it logs when you go offline and come back online.
• Notifications arrive fastest (every 5 seconds) when you are viewing a ticket, so you will see updates from colleagues almost immediately during active collaboration.

Archive (Completed Items)

The Archive view (labeled "Completed" in the header bar) shows all work items that have been completed or archived. From here, you can review past work, restore items to active status, or permanently move them to the trash.

Accessing the Archive

• Click Completed in the header bar
• Press Ctrl+2

Toolbar

Search

Type in the search field (placeholder: "Search completed items...") to filter by title, ticket number, task code, or description. Search updates with a 300ms debounce.

Sort

Sort Field

Choose from 8 sorting options:

• Date Completed (default) — when the item was last modified/completed
• Date Created — when the item was originally created
• Title — alphabetical
• Type — grouped by item type
• Urgency — Critical, High, Medium, Low order
• Ticket # — by ticket or task code
• Assigned To — by assignee name
• Customer — by customer name

Sort Direction

Toggle between descending (↓) and ascending (↑). Your sort preferences are saved between sessions.

Refresh

Click the refresh button (↻) to reload completed items from the server. The button is disabled during loading.

Type Filter Tabs

Four tabs filter the list by item type:

Completed Item Cards

Each completed item appears as a card similar to the Inbox cards, with some differences:

Card Contents

• Color bar — left edge color strip from the item's color tag
• Title — with search highlighting if applicable
• Task type badge — if a task type was assigned (e.g., "Installation", "Repair")
• "Completed" chip — green badge always shown for archived items
• Signature status chip (service tickets only) — "Signed", "Awaiting", etc.
• Item type chip — Task, Service Ticket, or Support Ticket
• Ticket/task code — the item's identifier
• Urgency chip — shown for High or Critical items
• Equipment info — equipment name and problem description (if applicable)
• Completion metadata — "Completed [date] by [username]"
• Emoji indicators:
• 📎 if the item has attachments
• 🌴 if the urgency was Low

Actions

Viewing an Item

Double-click a completed item to open its detail view. This lets you review all the information even after the item has been archived.

Restoring an Item

To move a completed item back to active status:

1. Select the item in the list.
2. Click the Restore button (↩️) at the bottom of the view, or right-click and select Restore.
3. Confirm in the dialog: "Restore [title] to active items?"

The item will reappear in your Inbox as an active work item.

Moving to Trash

To permanently discard a completed item:

1. Select the item in the list.
2. Click the Move to Trash button (🗑️) at the bottom, or right-click and select Move to Trash.
3. Confirm in the dialog: "Move [title] to trash? This cannot be undone."

Trashed items can be recovered by an administrator from the Admin Panel's Trash tab (see Admin Panel).

Right-Click Context Menu

Right-click any item for quick access to:

• View — open the detail view
• Restore — return to active items
• Move to Trash — permanently discard

Loading

Completed items are loaded asynchronously. A loading overlay with animated dots appears while data is being fetched. The list enriches items with user display names for the "completed by" metadata.

Tips

• Use sort by Date Completed (the default) to see your most recently finished work at the top.
• The search field is useful for finding past tickets when a customer calls back about a previously resolved issue.
• Restore is non-destructive — it simply moves the item back to active status, preserving all its data.
• Use type filter tabs to quickly narrow down to just service tickets, support tickets, or tasks.
• The status bar shows how many items match your current filter (e.g., "12 items").

Settings & Preferences

The Settings view lets you manage your profile, customize the application's appearance and behavior, configure security options, and view application information.

Accessing Settings

• Click the Settings button (profile picture or gear icon) in the header bar, then select User Settings
• Press Ctrl+9

Profile Tab

The Profile tab manages your personal information and profile picture.

Profile Picture

Your profile picture appears as a circular thumbnail at the top of the tab.

Changing Your Picture

1. Click Change Picture.
2. Select an image file from the file dialog (supported formats: PNG, JPG, JPEG, BMP, WebP).
3. A cropping tool appears with a 200×200 circular preview.
4. Adjust the image:

• Use the Scale slider (50%–300%) to zoom in or out
• Click and drag the image to reposition it within the circle

1. Click Upload Cropped Picture to save your new profile picture.

Your profile picture appears in the header bar, in chat messages, and next to read receipts.

Removing Your Picture

Click Remove Picture and confirm. Your avatar will revert to the default gear icon in the header.

Profile Information

Edit your personal details:

• Full Name — your complete name
• First Name — first name only
• Last Name — last name only
• Nickname — display name used in the app
• Email — your email address
• Phone — your phone number (format: (555) 123-4567)
• Username — read-only, set by your administrator
• Role — read-only, shows your permission level (User or Admin)
• Team — read-only, shows your team assignment

Chat Color

Set a custom color for your name in chat messages:

1. Enter a hex color code in the text field, or
2. Click Pick Color to open a color picker dialog.
3. A preview swatch shows your selected color.

Change Password

1. Enter your Current Password.
2. Enter your New Password.
3. Enter your new password again in Confirm Password.
4. Click Change Password.

Saving

Click Save Profile to save all profile changes. A success message confirms the save.

Preferences Tab

The Preferences tab controls the application's appearance and behavior.

Appearance

Theme

Choose your visual theme:

• System (default) — follows your operating system's light/dark mode setting
• Light — always use the light theme
• Dark — always use the dark theme

The theme changes apply immediately when you select a new option.

Text Size

Adjust the application's font size:

• Small — 12px base
• Medium — 14px base (default)
• Large — 16px base
• Extra Large — 18px base

Name Color in Chat

Set the color used for your display name in private chat. Enter a hex code or click Pick to open the color picker.

Behavior

Auto-refresh

How often the application polls for data updates:

• 15 seconds
• 30 seconds (default)
• 1 minute
• 5 minutes
• Manual (no automatic refresh)

Timezone

Select your local timezone from the dropdown. This affects how timestamps are displayed throughout the application. Options include:

• America/New_York, America/Chicago, America/Denver, America/Detroit
• America/Los_Angeles, America/Phoenix, America/Anchorage
• Pacific/Honolulu, UTC

Auto-sync on Reconnect

When checked, the application automatically syncs any pending offline changes when connectivity is restored. Enabled by default.

Notifications

Send Test Notification

Click this button to trigger a test notification through the system tray. This is useful for verifying that notifications are working on your system.

Saving

Click Save Preferences to persist your changes.

Security Tab

The Security tab manages credential storage and authentication options.

Credentials

Save Password

When checked, your login credentials are stored in your operating system's secure keychain (macOS Keychain, Windows Credential Manager). This allows the "Auto-login" feature to work.

Auto-login on Launch

When checked, the application attempts to log in automatically when launched using your saved credentials. Requires "Save Password" to be enabled.

Two-Factor Authentication

Enable 2FA

This option is currently disabled (grayed out) and will be available when server-side support is added.

Diagnostics

View Client Log

Click this button to open the application's log file in your system's default text viewer. The log file is located at:

~/.corejobtrack/logs/corejobtrack.log

This is useful for troubleshooting issues or providing information to support.

Saving

Click Save Security Settings to persist your changes.

About Tab

The About tab displays application information.

• App Version — the version of Corejobtrack Desktop you are running
• Server Version — the version of the Corejobtrack server you are connected to (loads asynchronously; shows "..." while loading, or "unavailable" if the server cannot be reached)

Tips

• The profile picture cropper supports dragging and scaling — position your face in the center of the circle for the best result.
• Auto-refresh at 15 seconds gives you the most up-to-date data but uses more network traffic. Manual refresh is best for slow or metered connections.
• Your chat color makes your messages stand out in team discussions. Choose a color that is easily distinguishable from your teammates.
• The View Client Log button in Security is your first stop when troubleshooting — share the log file with support for faster resolution.
• Theme set to "System" is recommended — it automatically matches your OS preference and changes when you switch between light and dark mode at the system level.

Admin Panel

The Admin Panel is available to users with the Administrator role. It provides tools for managing users, recovering deleted items, viewing server logs, monitoring server health, and configuring system-wide defaults.

Accessing the Admin Panel

• Click the Settings button (profile picture) in the header bar, then select Admin Settings
• The Admin Settings option only appears if your account has admin privileges

Users Tab

Manage all user accounts in the system.

User List

All users are displayed in a list with the format:

username (role) — Display Name

Adding a User

1. Click Add User.
2. Enter the new username in the first dialog.
3. Enter the initial password in the second dialog (the password field is masked).
4. The user is created on the server and appears in the list.

Deleting a User

1. Select a user in the list.
2. Click Delete User.
3. Confirm the deletion in the dialog.

Refreshing

Click Refresh to reload the user list from the server.

Trash Tab

The Trash tab lets you manage items that have been deleted or moved to trash by users.

Trash List

Deleted items appear with their type and title:

[service_ticket] Printer Repair - Acme Corp
[task] Update inventory spreadsheet

Actions

Restore

Select an item and click Restore to return it to its original location (active or completed).

Delete Forever

Select an item and click Delete Forever to permanently remove it from the system. A confirmation dialog warns: "This cannot be undone."

Empty Trash

Click Empty Trash to permanently delete all items in the trash at once. A confirmation dialog warns about the bulk deletion.

Refresh

Click Refresh to reload the trash contents.

Server Logs Tab

View recent server log output for troubleshooting.

Log Viewer

A read-only text area displays up to 200 lines of server log output in monospace font. The log shows server-side events, errors, and activity.

Refreshing

Click Refresh to reload the latest log entries.

Server Info Tab

View details about the server environment and infrastructure.

Information Displayed

Server Version

The current version of the Corejobtrack server.

SSL Certificate

Details about the server's SSL certificate:

• Issuer
• Subject
• Expiration date (not_after)
• Serial number

Database Status

Key-value pairs from the database schema status check, showing the health and configuration of the server database.

Refreshing

Click Refresh to reload all server information.

Ticket Defaults Tab

Configure system-wide default settings for new tickets.

Color Pickers

Service Ticket Color

Click the color button to open a color picker and set the default color for new service tickets. The selected hex code is displayed on the button.

Support Ticket Color

Click the color button to set the default color for new support tickets.

Saving

Click Save Defaults to persist the selected colors to the server. These defaults apply to all users when creating new tickets.

Tips

• Always confirm before using "Delete Forever" or "Empty Trash" — these actions are permanent and cannot be recovered.
• Check Server Logs when investigating issues reported by users — they show server-side errors and can help identify problems.
• The SSL Certificate section is useful for monitoring certificate expiration — plan renewals before the certificate expires.
• Ticket default colors help your team visually distinguish between service and support tickets in the Inbox.

Templates & Task Types

Templates and task types help standardize and speed up the creation of new work items. Templates provide pre-filled content for new tasks, while task types categorize work into meaningful groups.

Accessing Templates

• Click Templates in the header bar
• Press Ctrl+7

Templates Tab

Templates are reusable blueprints for creating new tasks. When you create a task "From Template" in the Inbox, the template's fields are automatically filled in.

Template List

All available templates appear in a list showing the template name.

What Templates Include

A template can define:

• Name — the template's identifier (what you see in the selection list)
• Title — pre-filled task title
• Description — pre-filled task description
• Color — default color tag for the task
• Task Type — default category assignment
• Steps — pre-defined checklist items
• Due Date Offset — how many days from creation the task is due (default: 7 days)
• Default Assignees — users and teams automatically assigned

Creating a Template

1. Click New Template.
2. Enter a name for the template in the first dialog.
3. Optionally enter a description in the second dialog.
4. The template is created on the server and appears in the list.

Note: To fully configure a template with steps, assignees, and other fields, use the web admin portal for now. The desktop client currently supports creating, naming, and deleting templates.

Deleting a Template

1. Select a template in the list.
2. Click Delete.
3. Confirm the deletion.

Using a Template

To create a task from a template:

1. In the Inbox, click the + New button.
2. Select From Template... from the dropdown.
3. A dialog appears listing all available templates.
4. Select a template and click OK.
5. A new task is created with the template's title, description, color, task type, and steps pre-filled.

If no templates are available, an informational message appears.

Task Types Tab

Task types are categories that can be assigned to any work item (tasks, service tickets, support tickets). They appear as colored badges on item cards in the Inbox and Archive.

Task Type List

All defined task types appear in a list showing their names.

Creating a Task Type

1. Click New Type.
2. Enter the type name in the dialog (e.g., "Installation", "Repair", "Part Lookup", "Training").
3. The type is created on the server.

Deleting a Task Type

1. Select a type in the list.
2. Click Delete.
3. Confirm the deletion.

How Task Types Appear

When a task type is assigned to a work item, it appears as a colored badge on the item's card in the Inbox and Archive views. The badge color can be set per type, or a deterministic pastel color is generated from the type name.

Tips

• Create templates for your most common recurring tasks — things like "Weekly Report", "Monthly Maintenance", or "New Customer Onboarding".
• Task types help you categorize and filter work. Common examples include: Installation, Repair, Diagnostic, Part Lookup, Training, Delivery.
• When creating tasks "From Template", you can still modify any pre-filled fields before saving — the template gives you a starting point, not a locked form.
• Use task types consistently across your team so everyone can filter and sort by the same categories.

Private Chat

Private Chat is an embedded real-time messaging feature available within every work item (tasks, service tickets, and support tickets). It provides a space for internal team communication that is linked directly to the work item, keeping discussions in context.

Overview

Private Chat appears as:

• A tab in the task and support ticket detail views
• A collapsible section in the service ticket detail view

It is only available for saved (existing) items — you must save a new work item before the Private Chat area appears.

Chat Interface

Message Display

Messages appear as chat bubbles in a scrollable area:

• Your messages appear on the right side with a light blue background
• Other people's messages appear on the left side with a gray background

Each message shows:

• Avatar — a circular image (28px) showing the sender's profile picture, or their initials on a colored circle if no picture is available
• Sender name — displayed in bold above the message, with a unique color per user
• Timestamp — shown in small text, converted to your local timezone (e.g., "Jan 5, 3:45 PM")
• Message content — the text of the message (word-wrapped and selectable)

Sender Colors

Each user gets a unique, deterministic color for their name in chat. This color is computed from the user's ID, so it is consistent across all tickets and sessions. Users can also set a custom chat color in Settings.

Resizing the Chat Area

The chat scroll area can be resized by dragging its bottom edge:

• Hover over the bottom edge of the chat area — your cursor changes to a vertical resize arrow (↕)
• Click and drag up or down to shrink or expand the area
• Minimum height: 150px
• Maximum height: 800px
• Default height: 300px

Sending Messages

1. Type your message in the input field at the bottom of the chat (placeholder: "Type a message...").
2. Press Enter to send, or click the Send button.
3. To insert a new line without sending, press Shift+Enter.

Your message is immediately sent to the server and appears in the chat.

If an error occurs while sending, your message text is restored to the input field so you do not lose it.

Deleting Messages

You can delete your own messages:

1. Hover over one of your messages.
2. Click the X button that appears (red/pink color).
3. The message is removed from the conversation.

You can only delete messages you sent — the delete button does not appear on other people's messages.

Typing Indicators

When another team member is actively typing in the same chat, a typing indicator appears below the messages:

• One person: "John is typing..."
• Two people: "Jane and Bob are typing..."
• Three or more: "Alice, Bob and 2 more are typing..."

The indicator includes animated dots that cycle (., .., ...) to show activity. The indicator disappears when the other person stops typing.

Your typing status is also reported to others. The system rate-limits typing reports to once every 2.5 seconds to avoid excessive server traffic.

Read Receipts

Small circular avatars (16px) appear below messages to indicate who has read up to that point.

• Each avatar represents a team member who has read the conversation up to (and including) that message
• Up to 5 reader avatars are shown per message
• Hover over an avatar to see the reader's name in a tooltip
• Your own read receipt is not shown (you already know you have read it)

Read receipts update every 9 seconds (every third polling cycle).

Real-Time Updates

Private Chat polls the server every 3 seconds for new messages. This means:

• Messages from other team members appear within a few seconds of being sent
• Typing indicators update in near real-time
• You do not need to manually refresh to see new messages

The polling automatically starts when you view the chat and stops when you navigate away, minimizing unnecessary network traffic.

Message Format

Messages are stored as plain text with timestamps and user identification. The format supports:

• Regular text messages
• Multi-line messages (using Shift+Enter when composing)
• Messages are sanitized to prevent formatting issues

Tips

• Enter sends, Shift+Enter adds a new line — this is the standard chat convention used in most messaging apps.
• Use Private Chat instead of external messaging tools — keeping discussions inside the ticket provides context for future reference.
• Read receipts let you know if your team has seen your message without needing to ask.
• Typing indicators prevent awkward message collisions — wait if you see someone else is typing.
• The chat area remembers its size between visits — resize it once to your preferred height and it stays that way.
• Private Chat is internal only — customers and external contacts cannot see these messages. Use the Communication Log in support tickets or Public Notes for customer-visible content.

Offline Mode & Sync

Corejobtrack Desktop is designed for offline-first operation. You can continue working even when your internet connection is unavailable, and your changes will automatically sync when connectivity is restored.

How Offline Mode Works

Network Monitoring

The application continuously monitors your connection to the Corejobtrack server by performing periodic health checks. The current status is shown in two places:

Login Screen

A colored dot and text label at the bottom:

• Green + "Online" — connected to the server
• Orange + "Poor Connection" — server is reachable but slow (response time ≥ 2 seconds)
• Red + "Disconnected" — cannot reach the server

Main Window Status Bar

A colored dot on the left side of the status bar with the same color coding. Hover over it for a tooltip ("Connected", "Slow connection", "No connection", or "Checking connection...").

What Happens When You Go Offline

When connectivity is lost:

1. The status indicator turns red.
2. Data that was already loaded remains visible and usable.
3. Any changes you make (creating, editing, or deleting work items) are queued in a local outbox stored in your SQLite database.
4. A dialog confirms: "You are offline. Changes have been queued and will sync when connected."
5. The status bar shows the number of pending changes (e.g., "3 pending changes").

What Happens When You Come Back Online

When connectivity is restored:

1. The status indicator turns green.
2. If Auto-sync on reconnect is enabled (default), the sync service immediately begins processing your queued changes.
3. Changes are sent to the server one at a time in the order they were made.
4. The pending changes count decreases as each change is successfully synced.

The Outbox (Sync Queue)

The outbox is a local queue that stores your offline changes until they can be sent to the server.

What Gets Queued

Any create, update, or delete operation on:

• Tasks
• Service tickets
• Support tickets
• Customers

Queue Processing

Changes are processed in FIFO order (first in, first out) based on when they were queued.

For each queued change:

• Create operations → POST to the server
• Update operations → PATCH to the server
• Delete operations → DELETE on the server

Retry Logic

If a queued change fails to sync:

• The system retries up to 5 times.
• After 5 failed attempts, the change is marked as "failed" and stops retrying.
• An error message is recorded with each failed attempt for troubleshooting.

Sync Interval

The sync service checks for pending changes on a configurable interval (default: every 30 seconds). You can change this in the .env file with SYNC_INTERVAL_SECONDS.

Local Data Cache

To support offline access, the application caches data locally in a SQLite database.

What Is Cached

• Tasks
• Service tickets
• Support tickets
• Customers

Cached data is stored as JSON in the local database at:

~/.corejobtrack/corejobtrack_local.db

How Caching Works

• Data is cached each time it is fetched from the server.
• When offline, views can display cached data instead of showing empty screens.
• Customer search works offline against cached records.

Database Mode

The local database uses WAL mode (Write-Ahead Logging), which allows reading data even while writes are in progress. This prevents lock conflicts and improves reliability.

Authentication and Offline

Token Management

Your authentication token (JWT) lasts for 12 hours. The application proactively refreshes it every 10 hours to prevent unexpected expiration.

If the token expires while you are offline:

1. When connectivity returns, the application attempts a silent re-authentication using your saved keychain credentials (if "Save Password" is enabled).
2. If re-authentication succeeds, normal operation resumes.
3. If it fails (e.g., your password changed), a session expired notification appears, and you are returned to the login screen.

Keychain Storage

Saved credentials are stored securely in your operating system's keychain:

• macOS: Keychain Access
• Windows: Credential Manager
• Linux: SecretService (GNOME Keyring or KDE Wallet)

Settings Persistence

Your preferences are stored locally and always available, even offline:

In SQLite (settings table):

• Theme preference
• Text size
• Auto-refresh interval
• Timezone
• Sort preferences
• Filter preferences
• Auto-login and save password flags

In JSON file (~/.corejobtrack/ui_preferences.json):

• Window position and size
• Collapsible section expand/collapse states per view

In OS Keychain:

• Login credentials (if "Save Password" is enabled)
• Authentication token

Troubleshooting Offline Issues

"Pending changes" counter is not decreasing

• Check your connection status in the status bar. If it shows red, you are still offline.
• Verify the server is reachable. The app pings the server's health endpoint every 10 seconds.
• Check if auto-sync is enabled in Settings > Preferences > "Auto-sync on reconnect".

Changes failed to sync

• After 5 retries, failed changes stop retrying automatically.
• Check the application log file at ~/.corejobtrack/logs/corejobtrack.log for error details.
• You can view the log from Settings > Security > "View Client Log".

App shows stale data

• Press Ctrl+R to manually refresh the current view.
• The application may be showing cached data. A successful refresh fetches the latest from the server.

Authentication expired

• If you are returned to the login screen unexpectedly, your token may have expired while offline.
• Log in again to get a fresh token. Your pending offline changes will still be in the queue and will sync after login.

Tips

• Enable "Save Password" in Settings > Security to allow silent re-authentication. This prevents being locked out after long offline periods.
• Enable "Auto-sync on reconnect" (on by default) so you do not have to manually trigger sync after coming back online.
• The pending changes counter in the status bar is your best indicator of offline queue status — check it to see if changes are waiting to sync.
• If you are on a slow or metered connection, consider setting the auto-refresh interval to a longer value (1 or 5 minutes) to reduce data usage.
• The local database at ~/.corejobtrack/ is safe to back up if you want to preserve your cached data and settings.

Themes & Appearance

Corejobtrack Desktop features a full theme system with dark and light modes, adjustable text sizes, and a Catppuccin-inspired color palette. You can customize the appearance to suit your preferences and working environment.

Theme Modes

The application supports three theme modes:

System (Default)

Follows your operating system's appearance setting:

• macOS: Detects light/dark mode from System Preferences
• Windows: Detects from the Windows Registry personalization setting
• Linux: Falls back to Qt palette inspection

When your OS switches themes (e.g., scheduled dark mode at sunset), the application follows automatically.

Dark Mode

A dark color scheme based on the Catppuccin Mocha palette:

• Dark navy background (#1e1e2e)
• Light text (#cdd6f4)
• Blue accents (#89b4fa)
• Reduced eye strain in low-light environments

Light Mode

A light color scheme based on the Catppuccin Latte palette:

• Off-white background (#eff1f5)
• Dark text (#4c4f69)
• Blue accents (#1e66f5)
• High contrast for bright environments

Switching Themes

There are three ways to switch themes:

Quick Toggle

Click the theme toggle button in the header bar (far right):

• In dark mode: shows a ☀ (sun) icon — click to switch to light mode
• In light mode: shows a ☾ (moon) icon — click to switch to dark mode

This toggles between light and dark, overriding the "System" setting.

View Menu

Use the menu: View > Appearance and select:

• System — auto-detect from OS
• Light — force light theme
• Dark — force dark theme

A checkmark indicates the current selection.

Settings

In Settings > Preferences > Appearance, select your theme from the dropdown.

Your theme preference is saved and restored across sessions.

Text Size

Adjust the base font size for the entire application:

Change text size in Settings > Preferences > Text Size. The change applies immediately.

Color System

Status Colors

Work item statuses use consistent colors throughout the application:

Urgency Colors

Priority levels are color-coded:

Item Type Colors

Work item types have distinct colors:

• Task — gray
• Service Ticket — blue
• Support Ticket — purple

UI Elements Affected by Theme

When you switch themes, the following elements update:

• Header bar: Logo switches between white and blue variants; home icon recolors; logout icon switches variants
• All text: Colors adjust for readability against the new background
• Buttons: Background, hover, and pressed states change
• Input fields: Border and focus colors adjust
• Scrollbars: Handle colors change
• Status badges and chips: Colors remain consistent but borders/shadows adjust
• Chat bubbles: Background tints adjust
• List items: Selection highlights and alternating row colors change

Cursor Behavior

The application automatically displays a pointing hand cursor (👆) when hovering over any clickable element — buttons, tabs, and interactive widgets. This provides consistent visual feedback across the entire application.

Tips

• System mode is recommended for most users — it automatically matches your OS and respects scheduled light/dark mode transitions.
• Dark mode reduces eye strain during evening work or in dimly lit environments.
• Extra Large text is helpful when sharing your screen or presenting during meetings.
• The theme changes instantly — there is no need to restart the application.
• Color-coded badges (status, urgency, item type) use the same hue in both themes, so you can learn the color associations once and recognize them in either mode.