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.

    • 3. 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

    4. Copy the environment template and configure it:

    
   cp .env.sample .env

    5. Edit .env to set your server URL and other options (see Configuration below).

    6. Run the application:

    
   python main.py

    ---


    Configuration


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


    SettingDefaultDescription
    `SERVER_URL``https://your-server.example.com`Your Corejobtrack server address
    `SSL_VERIFY``true`Whether to verify SSL certificates
    `SYNC_INTERVAL_SECONDS``30`How often offline changes sync (in seconds)
    `LOG_LEVEL``INFO`Logging detail level

    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


    • 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


    ShortcutAction
    Ctrl+RRefresh current view
    Ctrl+QQuit application
    Ctrl+NNew Task
    Ctrl+Shift+NNew Service Ticket
    Ctrl+Alt+NNew Support Ticket
    Ctrl+1Go to Home
    Ctrl+2Go to Completed
    Ctrl+3Go to Customers
    Ctrl+4Go to Contacts
    Ctrl+5Go to Equipment
    Ctrl+6Go to Vendors
    Ctrl+7Go to Templates
    Ctrl+8Go to Notifications
    Ctrl+9Go to Settings

    ---


    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.



    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:


    TabShows
    **All**Every active item
    **Service**Service tickets only
    **Support**Support tickets only
    **Tasks**Tasks only

    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.



  • **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.



  • **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


    • 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.



  • **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.



  • **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:


    StatePoll IntervalWhen Active
    ActiveEvery 10 secondsYou are clicking, typing, or interacting with the app
    Viewing a ticketEvery 5 secondsYou have a ticket detail view open
    IdleEvery 30 secondsNo interaction for 2+ minutes
    MinimizedEvery 60 secondsThe app window is minimized

    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



    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:


    TabShows
    **All**Every completed/archived item
    **Service**Service tickets only
    **Support**Support tickets only
    **Tasks**Tasks only

    ---


    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

    • 5. 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:


    SettingBase SizeBest For
    Small12pxFitting more content on screen
    Medium14pxDefault, balanced readability
    Large16pxEasier reading at arm's length
    Extra Large18pxAccessibility and large displays

    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:


    StatusDark ModeLight Mode
    OpenBlue (#89b4fa)Blue (#1e66f5)
    PausedYellow (#f9e2af)Yellow (#df8e1d)
    CompletedGreen (#a6e3a1)Green (#40a02b)
    ArchivedGray (#6c7086)Gray (#8c8fa1)
    TrashRed (#f38ba8)Red (#d20f39)

    Urgency Colors


    Priority levels are color-coded:


    UrgencyColor
    LowGreen
    MediumYellow
    HighRed/Orange
    CriticalPurple

    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.