From 261ded958096cdf35ee38ba698351c903e810e70 Mon Sep 17 00:00:00 2001 From: Johannes Date: Wed, 1 Jul 2026 00:36:22 -0400 Subject: [PATCH] content(guide): fleet.tasks / fleet.artifacts / fleet.patch-windows markdown (Refs #1) Ported from the previously-hardcoded GuidePanel objects in hiveops-fleet. Co-Authored-By: Claude Opus 4.8 --- .../content/fleet/artifacts/overview.md | 28 +++++++++++++ .../content/fleet/patch-windows/overview.md | 41 +++++++++++++++++++ .../resources/content/fleet/tasks/overview.md | 41 ++++++++++++++++--- 3 files changed, 104 insertions(+), 6 deletions(-) create mode 100644 backend/src/main/resources/content/fleet/artifacts/overview.md create mode 100644 backend/src/main/resources/content/fleet/patch-windows/overview.md diff --git a/backend/src/main/resources/content/fleet/artifacts/overview.md b/backend/src/main/resources/content/fleet/artifacts/overview.md new file mode 100644 index 0000000..3bb6a64 --- /dev/null +++ b/backend/src/main/resources/content/fleet/artifacts/overview.md @@ -0,0 +1,28 @@ +--- +module: fleet.artifacts +title: Artifact Import Guide +tab: Overview +order: 10 +audience: customer +--- + +Import the packages you deploy to devices — agents, hotfixes, and third-party software. + +## 🤖 Import Agent +1. Fetches the latest HiveOps Agent release from the CDN manifest. +2. Pulls all available packages — patch JARs and standard full installers — for each platform (Windows, Linux). +3. Import the patch package to create an **UPDATE_AGENT** fleet task that pushes agent upgrades to devices. + +> Use patch packages (small, agent core only) for regular upgrades. + +## 🔧 Import Hotfix +1. Fetches hotfix packages from the CDN manifest at `cdn.bcos.cloud`. +2. Hotfix artifacts are deployed to devices via a **UPDATE_HOTFIX** fleet task without requiring an agent update. + +> Use for urgent patches, customer-specific fixes, or OS-level updates. + +## 📦 Import Software +1. Fetches third-party software packages from the CDN software manifest. +2. Deploy via **UPDATE_SOFTWARE** fleet tasks to install or update third-party applications. + +> New packages are uploaded via the Browser CDN tool. diff --git a/backend/src/main/resources/content/fleet/patch-windows/overview.md b/backend/src/main/resources/content/fleet/patch-windows/overview.md new file mode 100644 index 0000000..0430046 --- /dev/null +++ b/backend/src/main/resources/content/fleet/patch-windows/overview.md @@ -0,0 +1,41 @@ +--- +module: fleet.patch-windows +title: Patch Window Guide +tab: Overview +order: 10 +audience: customer +--- + +How to schedule and manage ATM maintenance windows. + +## 🕐 What is a Patch Window? +1. A Patch Window defines a recurring time slot when ATMs are allowed to install hotfixes. +2. ATMs assigned to a window will only run **HOTFIX_INSTALL** tasks during that window — never outside of it. +3. Windows can recur **every week** on selected days, or on a **specific week of the month** (e.g. 2nd Tuesday). + +> HOTFIX tasks (immediate download) are not affected by patch windows — only HOTFIX_INSTALL. + +## ➕ Create a Patch Window +1. Click **+ New Patch Window** in the toolbar. +2. Enter a name and select the **institution** this window belongs to. +3. Select one or more **days of the week** when the window is active. +4. Optionally set a **Week of Month** to make it monthly (e.g. 1st week only). Leave blank for weekly recurrence. +5. Set the **start and end time** and select the correct **timezone**. + +> The window runs from start time to end time — keep it outside business hours. + +## 🏧 Assign ATMs to a Window +1. Click any window row in the table to open the ATM assignment panel. +2. ATMs currently assigned to that window are listed with their location. +3. To assign an ATM, edit the ATM record in Device Management and set its Patch Window. +4. To remove an ATM, click **Unassign** next to it in the panel. + +> An ATM can only belong to one patch window at a time. + +## 🚀 Using with HOTFIX_INSTALL Tasks +1. When a **HOTFIX_INSTALL** task is created for an ATM with a patch window, it is automatically scheduled for the next available window slot. +2. The scheduled time appears in the **Scheduled** tab in Fleet Tasks. +3. The task still requires **approval** before it will execute — approval can happen before the window opens. +4. If the ATM has no patch window assigned, the install runs immediately after approval. + +> Always assign a patch window to ATMs in live production environments. diff --git a/backend/src/main/resources/content/fleet/tasks/overview.md b/backend/src/main/resources/content/fleet/tasks/overview.md index 26f6079..a24938e 100644 --- a/backend/src/main/resources/content/fleet/tasks/overview.md +++ b/backend/src/main/resources/content/fleet/tasks/overview.md @@ -1,16 +1,45 @@ --- module: fleet.tasks -title: Fleet Tasks +title: Fleet Task Workflow tab: Overview order: 10 audience: customer --- -## What this is for +How to deploy hotfixes and software to ATMs. -**Fleet Tasks** is where you deploy software and hotfixes to ATMs and track their execution. +## 📤 Upload Hotfix to CDN +1. Go to **cdn.bcos.cloud/uploads.html** and log in with your credentials. +2. Obtain your upload code from the portal. +3. Upload your hotfix `.zip` file using the upload code. -A task moves through: **created → pending approval → running → completed** (or failed). Tabs -across the top separate **Current**, **Completed**, and **Failed** tasks, plus **Approvals**. +> This CDN upload step applies to HOTFIX artifacts only. -See the module-specific tabs for how to create and approve tasks. +## 📦 Import into Fleet Artifacts +1. Go to the **Artifacts** tab in Fleet Tasks. +2. Click **Import Hotfix from CDN** — available hotfixes on the CDN will be listed. +3. Click **Import** next to the hotfix you uploaded. +4. Once imported, click **Enable** on the artifact. + +> An artifact must be enabled before it can be used in a task. + +## 🚀 Create a Deployment Task +1. Click **Create Task** in the toolbar. +2. Select task kind: **HOTFIX** to download and apply immediately, or **HOTFIX_INSTALL** to schedule within a patch window. +3. Choose the imported artifact and select one or more target ATMs. +4. Submit — the task is created with status **Pending Approval** and will not execute until approved. + +## ✅ Approval +1. A user with fleet approver permission opens the **Approvals** tab. +2. They can add an optional note, then click **Approve** or **Reject**. +3. Approved tasks move to **Queued** and ATMs pick them up on the next check-in. + +> Rejected tasks are cancelled. The requester should be notified separately. + +## 🕐 Patch Windows (HOTFIX_INSTALL) +1. Assign a **Patch Window** to ATMs via device settings to control when installs run. +2. When a HOTFIX_INSTALL task is created, it auto-schedules within that window — the **Scheduled** tab shows the queued time. +3. The task still requires approval before it will execute. +4. If an ATM has no patch window assigned, the install runs immediately after approval. + +> Patch windows are defined in the Patch Windows tab.