Maintenance app

# BESS Maintenance App — User Guide

The maintenance app is integrated into the BESS Monitor dashboard as a dedicated panel. It provides work order management, team coordination, device status tracking, and availability monitoring for BESS sites.

URL: bess.paneco.energy → Maintenance tab

Table of Contents

1. Getting Started
2. Summary Widgets
3. Work Order List
4. Creating a Work Order
5. Work Order Detail
6. Status Workflow
7. Tasks (Checklists)
8. Description & Work Report
9. Comments
10. File Attachments
11. Assignees
12. Device Status Tracking
13. Team Management
14. Categories
15. Notifications
16. Deep Links
17. Roles & Permissions

1. Getting Started

Accessing the Maintenance Panel

1. Log in at https://bess.paneco.energy/
2. Click the Maintenance tab (wrench icon) in the tab bar
3. Select a site from the site selector if you have access to multiple sites

Who Can Use It

2. Summary Widgets

Three widgets appear at the top of the work order list:

3. Work Order List

Columns

Filtering

Tab-based filters across the top:

• OPEN — all non-terminal work orders (default)
• ALL — every work order
• REQUEST / ACTIVE / IN_PROGRESS / ON_HOLD / DONE / CLOSED / CANCELLED — filter by specific status

A search bar allows real-time filtering by title, device name, or assignee name.

Actions

• Click + New Work Order to create a new WO
• Click Team to manage site team members (admin only)
• Click any row to open the work order detail view

4. Creating a Work Order

Click + New Work Order from the list view.

Fields

Submission

Viewers see a note: "Your request will be reviewed by the maintenance team."

5. Work Order Detail

Opens as a full-width view with a two-column layout.

Left Column

Info Section

Request Banner

When viewing a WO in REQUEST status, users and admins see an action banner:

• Accept as Draft — moves to DRAFT status
• Accept as Active — moves to ACTIVE status
• Cancel — cancels the request

Description

Rich text editor with formatting toolbar (bold, italic, underline, lists, headers, links). Auto-saves after 1.5 seconds of inactivity. Click the expand icon to edit in a full-screen modal.

Tasks

Checklist section — see Tasks.

Work Report

Rich text editor for documenting what was done. Same features as Description. Typically filled when completing a work order.

Right Column

Comments

Chat-style message thread — see Comments.

Attachments

File upload area — see File Attachments.

Status History

At the bottom, a chronological log of all status changes showing:

• Date/time of change
• Status transition (e.g., "REQUEST → DRAFT")
• Who made the change
• Optional reason/note

Navigation

• Back button returns to the work order list
• Browser back is supported (popstate handling)

6. Status Workflow

Viewers submit ──► REQUEST ──────────────────────────────────┐
                                                              │
Users/Admins   ──► DRAFT ──► ACTIVE ──► IN_PROGRESS ────────┤
                                    │                         │
                                    ├──► ON_HOLD ────────────┤
                                    │                         │
                                    └────────────────────────┤
                                                              │
                                ┌─────────────────────────────┤
                                ▼             ▼               ▼
                              DONE         CLOSED        CANCELLED
                            (terminal)    (terminal)     (terminal)

Changing Status

1. Open the work order detail
2. Click the status dropdown in the info section
3. Select the new status
4. Optionally enter a reason/note in the confirmation dialog
5. The change is recorded in the status history

Terminal statuses (DONE, CLOSED, CANCELLED): attachments cannot be deleted once a WO reaches a terminal status.

7. Tasks (Checklists)

A checklist of subtasks within a work order.

Features

• Add task: Type a task description and click Add (or press Enter)
• Check off: Click the checkbox to mark a task as done
• Reorder: Drag tasks up/down using the drag handle (6-dot icon)
• Delete: Click the X icon to remove a task
• Progress bar: Shows completion percentage (e.g., "3/5 completed")

Tasks are only editable by users, partners, and admins. Viewers see a read-only view.

8. Description & Work Report

Both fields use a rich text editor (Quill.js) with the following toolbar:

Behavior

• Auto-save: Changes save automatically after 1.5 seconds of inactivity
• Expand: Click the expand icon to open a full-screen editor modal
• Images: Image paste/upload is blocked for security
• Viewers: See formatted HTML (read-only)

When to Use Each

• Description: Describe the issue, requirements, or planned work
• Work Report: Document what was actually done (typically filled when completing)

9. Comments

A chat-style message thread on the right side of the detail view.

Features

• Scrollable message history (auto-scrolls to latest)
• Each message shows: author name, timestamp, and message text
• Type in the input field and press Enter or click Send
• Messages are permanent (no edit or delete)

Who Can Comment

• Users, Partners, Admins: Can post comments
• Viewers: Read-only (no input field shown)

10. File Attachments

Upload and manage files attached to a work order.

Uploading

• Drag and drop files onto the upload zone, or click to browse
• Multiple files can be selected at once
• Maximum file size: 25 MB per file
• All common file types are supported

Managing

• Click a filename to download/open the file
• File size is shown next to each file
• Delete: Click the trash icon (available to the uploader or admins)
• Files cannot be deleted once a WO reaches a terminal status (DONE/CLOSED/CANCELLED)

11. Assignees

Team members assigned to work on a work order.

Viewing

Assignees appear as chips in the info section, showing the member's name or email.

Adding (Admins only)

1. Click + add next to the assignee chips
2. A dropdown shows available team members for the site
3. Members already assigned are filtered out
4. Click a name to assign them

Removing (Admins only)

Click the X on an assignee chip to remove them.

In Create Form (Users/Admins)

When creating a WO, click + add person to select from the site team roster.

12. Device Status Tracking

Track whether devices are online or offline, linked to work orders.

Viewing Device Status

• Work order list: Each row shows the device's status badge (ONLINE/OFFLINE)
• Work order detail: The device field shows an inline status badge

Changing Device Status (Users/Admins)

1. In the work order detail, click the device's status badge
2. A popup shows the current status and the proposed new status
3. Enter a reason (required) for the status change
4. Set the effective date/time (defaults to now)
5. Cascade option: If the device is a block with child strings, you can optionally set all child strings to the same status
6. Click Save

The status change is recorded in the device status log and linked to the current work order.

13. Team Management

Manage the roster of users who can be assigned to work orders for a site.

Accessing

Click Team from the work order list view (admin only).

Adding a Team Member (Admin)

1. Select from dropdown: Choose from known users (auto-populated from login activity). Users already on the team are filtered out.
2. Or select "Enter manually…" to type a name and email directly
3. Click Add

Removing a Team Member (Admin)

Click the trash icon next to a team member to remove them.

Why It Matters

• Team members appear in the assignee picker when creating or editing work orders
• For partner-maintenance users, team membership determines which sites they can access

14. Categories

Work orders can be tagged with a maintenance category:

• Set during creation or in the detail view
• Admins can rename categories via the API
• Categories are displayed in the work order list and detail view

15. Notifications

Badge

A red badge on the Maintenance tab shows the count of unread notifications (or "9+" if more than 9).

Polling

Notifications are checked every 60 seconds automatically. The badge updates without page refresh.

Types

Notifications are triggered by:

• Work order status changes
• New comments on work orders you're involved with
• Assignment changes

16. Deep Links

You can link directly to specific maintenance views using URL parameters:

These links respect role-based access — the user must be logged in and have access to the relevant site.

17. Roles & Permissions

Full Permission Matrix

Partner-Maintenance Role

External maintenance partners have a dedicated experience:

• Site access: Determined by team membership (not Auth0 site codes)
• UI: Only the Maintenance tab is visible — no Charts, 3D View, Test, or device list
• Permissions: Equivalent to User for maintenance features
• Cannot: Manage team, assign users, rename categories, or access telemetry panels

Viewer Experience

Viewers have a simplified interface:

• All editing fields appear as read-only text
• The create form shows only Title, Description, and Attachments
• Submit button says "Submit Request" instead of "Create Work Order"
• A note explains that requests will be reviewed by the maintenance team