Management UI Spec

1\ introduction the commandit platform utilizes agents across managed endpoints keeping these agents (service, ui, probe, updater) up to date is critical for security and functionality this document outlines the requirements for a management user interface (ui) within the commandit platform's "platform administration" section this ui will enable administrators to manage update packages, define update policies (building on agentupdatepolicies), monitor deployment status across the fleet, and configure core aspects of the auto update service 2\ goals & objectives centralized management provide a single interface within the commandit platform to manage all aspects of agent updates visibility & monitoring offer clear insights into the current versions of agents across devices, the status of ongoing updates, and historical update logs controlled rollouts enable administrators to manage update packages across different release channels (stable, beta, alpha) policy configuration allow administrators to define and manage agent update policies (agentupdatepolicies) dictating target versions and update schedules actionable insights facilitate troubleshooting by providing access to detailed update logs and allow administrators to trigger immediate updates when necessary ease of use ensure the ui is intuitive and efficient for administrators performing update management tasks 3\ target audience commandit platform administrators managed service provider (msp) technicians responsible for platform maintenance and agent deployment 4\ scope 4 1 in scope ui location reside within the "platform administration" section of the main commandit web application navigation provide a single entry point in the left navigation leading to a page with tabbed sections for managing agent updates overview dashboard tab display key summary statistics about agent versions and update status package management tab view list of available update packages view details of individual packages upload new pre built and pre signed agent update packages assign/move packages between release channels (stable, beta, alpha) mark packages as active/inactive update policy management tab view, create, edit, delete agent update policies configure policy details name, description, target versions, update schedule, staggering options view where policies are assigned deployment status monitoring tab view a list of managed devices with filtering/searching capabilities display current installed agent component versions display the assigned update policy and release channel for devices view recent update history/logs for selected devices trigger an immediate update check ("update now") for selected devices or groups configuration/settings tab display the configured update server url display default check interval display public key(s) used for signature verification (potentially allow uploading new public keys securely) 4 2 out of scope package building/signing the ui facilitates uploading existing signed packages; it does not include tools for building or signing them agent installation the ui monitors updates for existing agents; it is not the primary interface for initial agent deployment detailed device management full device inventory, remote control, or configuration management outside of agent versions and update status policy assignment mechanism while the ui shows where policies are applied, the primary mechanism for assigning policies might reside in other platform sections server infrastructure management managing the update server (updates commandit com) infrastructure itself client side updater logic this prd defines the management ui, not the behavior of the commandit updater client on the endpoint backend api implementation this document focuses on the ui; backend api development is assumed to be handled separately based on the data needs outlined here 5\ functional requirements 5 1 navigation & layout fr ui nav 001 provide a single navigation link in the "platform administration" section, labeled "agent updates" fr ui lay 001 clicking "agent updates" navigates to a single page with the title "agent updates" fr ui lay 002 this page will contain the following primary tabs, implemented using the commontabs reusable component dashboard deployments packages policies settings fr ui lay 003 employ a consistent layout across tabs, using standard ui components (tables, forms, buttons, modals) consistent with the commandit platform design system use the pageheader component for the main page title ("agent updates") use clear section titles within tabs 5 2 dashboard tab tab label dashboard content & functionality summary statistics widgets (fr ui ovr 001) implement using the dashboardcontainer and appropriate modules (numbermodule, chartmodule, listmodule see dashboard usage md) widgets require data fetched from backend apis providing aggregated counts/statuses widget "total managed devices" (numbermodule) link navigates to deployments tab widget "component versions (stable)" (chartmodule) link navigates to filtered deployments tab widget "devices pending update" (numbermodule) link navigates to filtered deployments tab widget "recent update failures (24h)" (numbermodule) link navigates to filtered deployments tab widget "available packages" (numbermodule or listmodule) link navigates to packages tab recent events feed (optional) (fr ui ovr 003) implement using listmodule requires data fetched from a backend api providing recent relevant events 5 3 deployments tab tab label deployments content & functionality filter controls (fr ui dep 002) implement using standard carbon components (dropdown, select, textinput) integrated with commondatatable's filtering capabilities or managed state filters should trigger api requests for updated table data devices table (fr ui dep 001) implement using the commondatatable reusable component data source fetch data from a backend api supporting pagination, sorting, and filtering based on the filter controls the api should return device data including org name, location name, os, arch, agent component versions, assigned policy name, release channel, last update status, and last update time columns define commontableheader array matching specified columns (device name, org name, location, os, arch, service ver, ui ver, probe ver, updater ver, assigned policy, channel, last update status \[use badge component], last update time) visual indicators (fr ui dep 005) apply conditional styling within commondatatable cell renderers based on comparison between device version and latest applicable version (data likely needed from api response or separate fetch) or last update status table actions (applied to selected rows fr ui dep 003, fr ui dep 004) implement using commondatatable's batch action capabilities or custom toolbar actions action "view update history" trigger opens a commonmodal modal content fetches data from a backend api (filtered by selected device ids) providing update log history and displays it using commondatatable columns timestamp, component, requested version, status, error message action "trigger update now" trigger opens a confirmation commonmodal on confirm calls a backend api endpoint for each selected device id to initiate an immediate update check display success/failure toast notification based on api response 5 4 packages tab tab label packages content & functionality action bar implement using standard carbon button button "upload package" (fr ui pkg 003) trigger opens a commonmodal modal content use dataentryform reusable component form fields (formfielddefinition array) component (type dropdown), version (type text, validation semver pattern), target os (type dropdown), target arch (type dropdown), package file (type file), release notes url (type url, optional), dependencies (type textarea, optional, validation json format) form submit calls a backend api to handle the upload, validation (including signature check), storage, and metadata creation handle api response (success/error) and refresh the table filter controls (fr ui pkg 002) implement using standard carbon components integrated with commondatatable filters trigger api requests packages table (fr ui pkg 001) implement using commondatatable data source fetch data from a backend api supporting pagination, sorting, and filtering api should return package data including component, version, channel, os, arch, published date, status (active/inactive), publisher name columns define commontableheader array matching specified columns (component, version, channel, os, arch, published date, status \[use badge], publisher) table actions (applied to selected rows via checkboxes fr ui pkg 004, fr ui pkg 005) implement using commondatatable's batch action capabilities action "assign channel" trigger opens commonmodal with a dropdown (stable/beta/alpha) submit calls backend api to update the channel for selected package ids refresh table action "set active" trigger calls backend api to set is active = true for selected package ids refresh table action "set inactive" trigger calls backend api to set is active = false for selected package ids refresh table action "view details" trigger opens commonmodal or side panel fetches full package details (including hash, signature) via api using package id and displays read only action "delete" trigger opens danger styled commonmodal for confirmation on confirm calls backend api to delete or mark inactive the selected package record refresh table 5 5 policies tab tab label policies content & functionality action bar implement using standard carbon button button "create policy" (fr ui pol 002) trigger opens a commonmodal or navigates to a dedicated create page use dataentryform form fields (formfielddefinition array) policy name (type text, required), description (type textarea), target versions (group per component service, ui, probe, updater; each with type dropdown \['latest stable', 'latest beta', 'latest alpha', 'specific version'] and conditional type text for specific version), update schedule (complex field potentially custom component or json input for start time, end time, timezone/utc, days of week), staggering (type number for delay minutes/hours), enable/disable (type toggle) form submit calls backend api to create a new policy record handle api response filter controls implement using standard carbon components integrated with commondatatable filters trigger api requests policies table (fr ui pol 001) implement using commondatatable data source fetch data from a backend api supporting pagination, sorting, and filtering api should return policy data including name, description, target version summary, schedule summary, status columns define commontableheader array matching specified columns (checkbox, name, description, target versions summary, schedule summary, status \[use badge]) table actions (applied to selected row fr ui pol 003, fr ui pol 004) implement using commondatatable's row actions or inline buttons action "edit" trigger opens modal/page with dataentryform pre filled with data fetched via api for the selected policy id submit calls backend api to update the policy action "delete" trigger opens danger styled commonmodal for confirmation on confirm calls backend api to delete the policy record (backend checks assignments) action "view assignments" trigger opens commonmodal or side panel fetches and displays a read only list (potentially using commondatatable) of orgs/tags assigned this policy (requires backend endpoint to query assignment source) refresh table on success for edit/delete 5 6 settings tab tab label settings content & functionality display fields (read only) use simple text display or read only textinput components fetch values from a backend configuration api field label update server url, value (e g , https //updates commandit com) (fr ui cfg 001) field label default agent check interval, value (e g , "4 hours") (fr ui cfg 002) public key management section title package signing public keys display use commondatatable to list keys fetch data from a backend api returning stored public keys (fingerprint, added date, status) (fr ui cfg 003) button "add public key" (fr ui cfg 004) trigger opens commonmodal form (use dataentryform) field for pasting pem key (type textarea, required) form submit calls backend api to validate and store the new key refresh key list on success row action (per key) "set inactive" trigger opens confirmation commonmodal on confirm calls backend api to mark the selected key as inactive refresh key list 6\ non functional requirements nfr ui perf 001 ui pages and tabs, especially tables with potentially large datasets (devices, packages, logs), must load and respond quickly employ pagination, server side filtering/sorting, and potentially lazy loading for tab content use commondatatable's server side capabilities nfr ui use 001 the interface should be intuitive for administrators familiar with it management concepts use clear, concise language (per carbon guidelines) provide helpful tooltips for less common actions or settings leverage standard patterns established by reusable components nfr ui sec 001 access to this ui section must be controlled by appropriate role based access control (rbac) within the commandit platform (e g , 'platformadmin' role) backend apis must enforce permissions for all actions (view, create, edit, delete, upload, trigger update) nfr ui sec 002 sensitive data (like signatures) should be displayed appropriately (e g , truncated or via view detail action) upload mechanisms must validate file types and potentially size on the client side before submitting to the backend for secure processing nfr ui acc 001 ui should adhere to accessibility standards (wcag 2 1 aa where feasible) ensure reusable components (commontabs, commondatatable, commonmodal, dataentryform) follow accessibility best practices 7\ ui/ux considerations data presentation use commondatatable for tabular data use dashboardcontainer with standard modules for the dashboard use commonmodal for dialogs use dataentryform for consistent form layouts feedback use carbon toastnotification for feedback on asynchronous actions (uploads, triggers, saves) use carbon inlineloading or skeleton states within components (commondatatable, dashboard modules) during data fetching consistency maintain consistency with the overall commandit platform's design language, components, and interaction patterns adhere to carbon design system principles error handling display user friendly error messages from api responses within modals, forms, or via toast notifications 8\ open issues / future considerations detailed rbac define the specific permissions required for each action within the ui (view packages vs upload packages vs assign channels) policy assignment ui determine where policies are assigned (here or elsewhere) and ensure visibility dashboard customization allow users to customize the overview dashboard? reporting add dedicated reporting features (e g , export deployment status, compliance reports) signing key management more robust ui for managing signing keys (rotation, revocation) package dependency visualization graphically display dependencies between packages 9\ development task breakdown (detailed ui focus) this section outlines the detailed tasks required to implement the agent updates management ui, referencing the functional requirements (fr) and reusable components it assumes backend apis providing the necessary data and handling actions are available phase 1 basic structure & navigation task ui 1 1 create agent updates page component goal establish the main react component for the agent updates page details create src/pages/platformadmin/agentupdatespage tsx manage tab state here ensure routing within platform admin task ui 1 2 implement page header goal display the main title details use pageheader component in agentupdatespage tsx set title="agent updates" (ref fr ui lay 003, pageheader) task ui 1 3 implement tab structure goal set up tab navigation details use commontabs component below pageheader define commontab\[] for dashboard, deployments, packages, policies, settings, providing labels and placeholder content implement state management for selected tab (ref fr ui lay 002, commontabs) task ui 1 4 add navigation link goal make page accessible details update platform admin left nav config to link "agent updates" to the new page route (ref fr ui nav 001) phase 2 dashboard tab implementation task ui 2 1 implement dashboard container goal set up widget container details place dashboardcontainer in the dashboard tab content area provide dashboardid (ref dashboardcontainer, dashboard usage md) task ui 2 2 fetch dashboard data goal retrieve aggregated data for widgets details implement data fetching hook(s) to call backend api(s) providing counts/stats for total devices, stable versions, pending updates, recent failures, available packages handle loading and error states task ui 2 3 implement dashboard widgets goal display summary statistics details create tileconfig\[] array define configurations using numbermodule, chartmodule, listmodule pass fetched data and loading state to modules (ref fr ui ovr 001) task ui 2 4 implement dashboard widget links goal navigate from widgets to relevant tabs details add onclick handlers or link components to navigate to deployments/packages tabs, potentially passing filter state update parent component's active tab state (ref fr ui ovr 002) task ui 2 5 (optional) implement recent events feed goal show recent activity details define tileconfig using listmodule fetch data from backend api for recent events format data for listmodule phase 3 deployments tab implementation task ui 3 1 implement deployment filter controls goal allow device list filtering details add carbon components (dropdown, select, textinput) for filters manage filter state trigger data refetch on filter change task ui 3 2 implement deployments table goal display device list and update status details use commondatatable define commontableheader for columns (fr ui dep 001) configure for server side data fetching (pagination, sorting, filtering) by calling the backend api with current state task ui 3 3 implement visual indicators goal highlight out of date/failed devices details use commondatatable formatter functions for version/status columns compare row data (versions) with latest applicable version data (fetched from api) and apply conditional styling/icons task ui 3 4 implement "view update history" action goal show detailed logs details add batch/row action on trigger open commonmodal fetch data from backend api (filtered by device ids) providing update logs display using commondatatable inside modal task ui 3 5 implement "trigger update now" action goal allow manual update initiation details add batch action on trigger open confirmation commonmodal on confirm call backend api for selected devices display toastnotification phase 4 packages tab implementation task ui 4 1 implement "upload package" action & form goal allow uploading new packages details add "upload package" button on click open commonmodal use dataentryform define formfielddefinition array for upload fields (component, version, os, arch, file, url, dependencies) with types and validation on submit call backend upload/validation api handle response, refresh table (ref fr ui pkg 003) task ui 4 2 implement package filter controls goal allow package list filtering details add carbon components for filters (component, channel, os, arch, status, search) manage state and trigger api refetch task ui 4 3 implement packages table goal display available packages details use commondatatable define commontableheader (component, version, channel, os, arch, published date, status \[badge], publisher) configure for server side data fetching from backend api (ref fr ui pkg 001) task ui 4 4 implement package table actions goal allow package lifecycle management details configure commondatatable batch actions "assign channel" opens commonmodal with dropdown submit calls backend api "set active"/"set inactive" calls backend api "view details" opens commonmodal/panel fetches full details via api and displays read only "delete" opens danger commonmodal on confirm, calls backend api refresh table on success for all actions (ref fr ui pkg 005) phase 5 policies tab implementation task ui 5 1 implement "create policy" action & form goal allow creation of new update policies details add "create policy" button on click opens commonmodal/page use dataentryform define formfielddefinition array (name, description, target versions \[grouped dropdowns/text], schedule ui, staggering, enable/disable toggle) on submit call backend create api handle response (ref fr ui pol 002) task ui 5 2 implement policy filter controls goal allow policy list filtering details add carbon textinput (search) and dropdown (status) manage state and trigger api refetch task ui 5 3 implement policies table goal display defined policies details use commondatatable define commontableheader (checkbox, name, description, target versions summary, schedule summary, status \[badge]) configure for server side data fetching from backend api (ref fr ui pol 001) task ui 5 4 implement policy table actions goal allow editing, deletion, viewing assignments details implement commondatatable row actions "edit" opens modal/page with dataentryform pre filled via api fetch submit calls update api "delete" opens danger commonmodal on confirm, calls delete api "view assignments" opens commonmodal/panel fetches assignment data via api and displays (e g , list) refresh table on success for edit/delete (ref fr ui pol 004) phase 6 settings tab implementation task ui 6 1 implement read only settings display goal show configured server url and interval details fetch data from backend config api display using read only textinput or text elements (ref fr ui cfg 001, fr ui cfg 002) task ui 6 2 implement public key list display goal show verification keys details fetch key data (fingerprint, added date, status) from backend api use commondatatable to display (ref fr ui cfg 003) task ui 6 3 implement "add public key" action & form goal allow adding new verification keys details add "add public key" button on click open commonmodal use dataentryform with textarea for pem key on submit call backend api to validate/store key refresh list (ref fr ui cfg 004) task ui 6 4 implement "set inactive" key action goal allow disabling old keys details add row action to keys table on click open confirmation commonmodal on confirm call backend api to mark key inactive refresh list phase 7 finalization & testing task ui 7 1 implement frontend rbac goal control ui elements based on user permissions details fetch user permissions wrap action buttons/elements in conditional rendering based on permissions task ui 7 2 implement api error handling goal provide user friendly feedback on backend errors details wrap api calls in try/catch parse errors and display using toastnotification or inline messages task ui 7 3 review copywriting goal ensure clear and concise ui text details review all labels, buttons, tooltips, titles align with carbon guidelines task ui 7 4 perform testing goal verify functionality, accessibility, robustness details write unit/integration tests perform e2e tests for all workflows perform accessibility checks task ui 7 5 verify responsiveness goal ensure ui adapts to different screen sizes details test page and tabs on desktop, tablet, mobile widths verify layouts and component behavior