> For the complete documentation index, see [llms.txt](https://asus-isg-aidc.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://asus-isg-aidc.gitbook.io/guide/latest/portal/jobmanagement.md).

# Job Management

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/04/14    |

![Job Management Feature](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/jobManagement/Job_Management.png)

## Feature Goal

### Aim

The Job Management feature provides a centralized interface for managing deployment jobs (templates) across the system. It enables users to:

* View all deployment and marketplace jobs in one list
* Create new deployment templates for OS installation or configuration
* Edit existing job templates
* Execute deployment jobs to target nodes
* Monitor job status and progress
* Duplicate jobs for reuse
* Delete obsolete jobs

### User Story

**As a** system administrator\
**I want** to manage all deployment jobs and their configurations from a single interface\
**So that** I can efficiently create, monitor, and execute deployment tasks across the cluster

## Feature Description

### 3.1 Location

* **Route**: `/DeploymentTemplateList`
* **Navigation Path**:
  * Side Menu: `Deploy Management` → `Deployment List`
* **Access Level**: Requires authenticated user with deployment management permissions

### 3.2 Reference Feature

**Related Features**:

* **Deployment Overview** (`/DeploymentOverview`): Monitor real-time deployment statistics and trends
* **Node Management** (`/NodeManagement`): Manage target nodes for deployment
* **Image Builder** (`/ImageBuilder`): Build and manage OS images for deployment
* **Marketplace** (`/Marketplace/Catalog`): Install services from marketplace

**Dependencies**:

* Jobs API for CRUD operations
* OS image service for image availability checking
* Deployment engine for job execution
* Node service for target selection

### 3.3 Operation Requirements

**Prerequisites**:

1. User must be authenticated and logged into the system
2. User must have deployment job management permissions
3. At least one node must exist in the system (for meaningful deployments)
4. OS images must be downloaded for OS deployment jobs

**Access Permissions**:

* View deployment jobs
* Create/edit/delete jobs
* Execute jobs
* Copy job templates

### 3.4 Operation Flow

**Main Workflow**:

1. **Initial Page Load**
   * System authenticates user
   * Fetches job list with pagination (fixed page size: 10 jobs per page)
   * Displays jobs in a card-list format with status indicators
   * Shows action buttons for each job
2. **Viewing Jobs**
   * User views jobs with key information (name, description, tag, node count, status, date, execution count)
   * User navigates through pages using pagination controls
   * User clicks a job row to expand and view its execution history inline
3. **Filtering & Sorting Jobs**
   * User enters keywords in the search bar; press Enter to apply
   * User selects a **Status** filter (All Status / Created / In Progress / Completed / Failed / Timeout)
   * User selects a **Tag** filter (All Tags / deployment / marketplace)
   * User selects a **Sort** option (Newest Updated / Oldest Updated / Newest Created / Oldest Created / Name A→Z / Name Z→A / Status A→Z)
   * Each filter change reloads the list from page 1
4. **Creating a New Job**
   * User clicks the **Create Job** button to open a dropdown menu
   * User selects one of:
     * **OS Deployment** → navigates to `/OSDeployment`
     * **Marketplace Services** → navigates to `/Marketplace/Catalog`
5. **Viewing Execution History**
   * User clicks anywhere on a job row to expand it
   * System shows an inline execution history table with columns: #, Status, Started At, Duration, Triggered By
   * User clicks an execution row to open the Execution Detail overlay panel
   * User clicks outside the panel or the close button to dismiss it
6. **Editing a Job**
   * User clicks the edit icon (✏️) on the job row
   * System opens the appropriate edit dialog based on job type
   * User modifies the job configuration and clicks Save
   * System validates and updates the job
   * Edit Job is disable for firmware jobs
7. **Executing a Job**
   * User clicks the **Execute** button on the job row
   * System calls the run API immediately
   * On success the job list refreshes to reflect the new status
   * Executing Job is disable for firmware jobs
8. **Copying a Job**
   * User clicks the copy icon on the job row
   * System opens a Copy Job dialog
   * User enters a new job name and clicks Copy
   * System creates a duplicate job; the list refreshes
   * Copying job is disable for firmware jobs
9. **Deleting a Job**
   * User clicks the delete icon (🗑️) on the job row
   * System shows a confirmation dialog: *"Are you sure you want to delete '\[job name]'? This action cannot be undone."*
   * User confirms deletion
   * System removes the job; the list resets to page 1 and refreshes
   * If deleting a firmware job, the execution record will also disappered in `Firmware Management` -> `Update History` list

### 3.5 UI Review

![Job Management UI Interface](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/jobManagement/Job_Management_UI_Interface_1.png)

The Job Management interface consists of a filter bar at the top and a scrollable job list below.

#### Filter Bar

| Control                  | Description                                                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Search bar (No.1)**    | Free-text search by job name or description; press Enter to apply                                                           |
| **Create Job (No.2)**    | Split button that opens a dropdown: **OS Deployment** → `/OSDeployment` / **Marketplace Services** → `/Marketplace/Catalog` |
| **Status filter (No.1)** | Dropdown: All Status / Created / In Progress / Completed / Failed / Timeout                                                 |
| **Tag filter (No.1)**    | Dropdown: All Tags / deployment / marketplace                                                                               |
| **Sort (No.1)**          | Dropdown: Newest Updated / Oldest Updated / Newest Created / Oldest Created / Name A→Z / Name Z→A / Status A→Z              |
| **Refresh**              | Reloads the job list from page 1                                                                                            |

#### Job List

Each job row displays:

| Field                 | Description                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Name(No.3)**        | Job name                                                                                                       |
| **Description(No.3)** | Short description of the job                                                                                   |
| **Tag(No.3)**         | Badge showing job category (deployment / marketplace)                                                          |
| **Nodes(No.3)**       | Number of target nodes                                                                                         |
| **Status(No.4)**      | Current effective status (derived from the latest execution, or the job's own status when no executions exist) |
| **Date(No.4)**        | Start time of the latest execution, or the job's own start time                                                |
| **Executions(No.4)**  | Total execution count                                                                                          |

**Status Badges**:

## Job Execution Status

| Status      | Description                                                                              |
| ----------- | ---------------------------------------------------------------------------------------- |
| Created     | The job has been created                                                                 |
| Queued      | The job has been queued and is waiting to run                                            |
| In Progress | The job is currently running                                                             |
| Completed   | The job finished successfully                                                            |
| Failed      | The job failed to execute                                                                |
| Timeout     | The job did not finish within the allowed time and was automatically marked as timed out |

> Timeout threshold: 1.25 hours (about 75 minutes). The system checks for timed-out jobs every 10 minutes.

## Node Execution Result

| Status  | Description                             |
| ------- | --------------------------------------- |
| Pending | No result yet; still waiting/processing |
| Success | The node executed successfully          |
| Failed  | The node failed to execute              |

**Action Buttons** (per row):

| Button        | Icon      | Behaviour                                               |
| ------------- | --------- | ------------------------------------------------------- |
| Execute(No.5) | ▶ Play    | Runs the job immediately; refreshes the list on success |
| Edit(No.6)    | ✏️ Pen    | Opens the edit dialog for the job                       |
| Copy(No.7)    | 📋 Copy   | Opens the Copy Job dialog                               |
| Delete(No.8)  | 🗑️ Trash | Opens the Delete confirmation dialog                    |

#### Expanded Execution History

Clicking a job row expands an inline table(No.9):

| Column       | Description                                  |
| ------------ | -------------------------------------------- |
| #            | Execution name / sequence number             |
| Status       | Status badge of that execution               |
| Started At   | Execution start timestamp (yyyy/MM/dd HH:mm) |
| Duration     | How long the execution ran                   |
| Triggered By | User or system that triggered the execution  |

Clicking an execution row opens the **Execution Detail** overlay panel.

#### Execution Detail

* Display Job name, description, and execution status(No.11)
* Display Execution sequence number, nodes count, stages, and duration(No.12)
* Show Execution Metadata, includes Triggered by account name, Tag, Started At, Updated At, Progress bar(No.13)
* Tabs that shows Tasks, Nodes, and Logs(No.14)
  * Tasks(No.15): Show all the tags and configured parameters / settings in each of the tasks. (For Ver1.4.0, there is only 1 stage for all the jobs)
  * Nodes(No.16): Show all the target nodes in this execution.
  * Logs(No.17): The detailed logs for each nodes. Shown up when the whole execution status is completed or timeout. If the execution is currently in progress and updating, logs won't show up.

#### Pagination (Footer)(No.10)

* Displays: *"Showing X to Y of Z jobs"*
* Fixed page size: **10 jobs per page** (no page-size selector)
* Previous / Next buttons; numbered page buttons with ellipsis for large page counts
* Previous button disabled on page 1; Next button disabled on the last page

### 3.6 Operation & Expected Result

#### Operation 1: View All Jobs

**Steps**:

1. Navigate to `/JobManagement`
2. Wait for the page to load

**Expected Result**:

* Page displays up to 10 jobs per page
* Each row shows name, description, tag, node count, status, date, and execution count
* Pagination controls appear at the bottom with total job count

***

#### Operation 2: Search / Filter / Sort Jobs

**Steps**:

1. Enter keyword(s) in the search bar and press Enter
2. Optionally select a Status, Tag, or Sort value from the dropdowns

**Expected Result**:

* List reloads from page 1 with matching results
* Status filter matches exact status values (Created, In Progress, Completed, Failed, Timeout)
* Tag filter limits results to the selected tag category
* Sort option changes the ordering of returned jobs

***

#### Operation 3: Create New Deployment Job

![Add New Deployment Job](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/jobManagement/Job_Management_Add_Jobs.png)

**Steps**:

1. Click the **Create Job** button
2. Select **OS Deployment** or **Marketplace Services** from the dropdown

**Expected Result**:

* Selecting **OS Deployment** navigates to `/OSDeployment`
* Selecting **Marketplace Services** navigates to `/Marketplace/Catalog`
* The dropdown closes after selection

***

#### Operation 4: View Execution History & Detail

**Steps**:

1. Click anywhere on a job row to expand it
2. Click an execution entry in the expanded table

**Expected Result**:

* Row expands to show the inline execution history table (#, Status, Started At, Duration, Triggered By)
* Clicking an execution row opens the **Execution Detail** overlay panel
* Clicking outside the panel or pressing close dismisses the overlay

***

#### Operation 5: Edit Existing Job

**Steps**:

1. Click the edit icon (✏️) on the target job row
2. Modify the desired fields
3. Click Save

**Expected Result**:

* Edit dialog opens pre-populated with the job's current values
* User can modify: name, description, targets, OS image / configuration
* Form validates changes before saving
* Job is updated; the list refreshes with the new values

***

#### Operation 6: Execute a Job

**Steps**:

1. Click the **Execute** button (▶) on the target job row

**Expected Result**:

* The run API is called immediately
* On success the job list refreshes; the job's status reflects the new execution state

***

#### Operation 7: Copy Job Template

**Steps**:

1. Click the copy icon on the target job row
2. Enter a new job name in the Copy Job dialog
3. Click Copy

**Expected Result**:

* Copy dialog opens with an input field for the new name
* On confirmation a duplicate job is created with the new name and **Created** status
* The original job is unchanged; the list refreshes to show both jobs

***

#### Operation 8: Delete Job

**Steps**:

1. Click the delete icon (🗑️) on the target job row
2. Confirm deletion in the dialog

**Expected Result**:

* Confirmation dialog shows the message: *"Are you sure you want to delete '\[job name]'? This action cannot be undone."*
* On confirmation the job is removed from the database
* The list resets to page 1 and refreshes; the deleted job no longer appears

***

#### Operation 9: Navigate Pages

**Steps**:

1. Click Previous / Next buttons or a numbered page button

**Expected Result**:

* Previous button is disabled on page 1; Next button is disabled on the last page
* Page indicator shows *"Showing X to Y of Z jobs"*
* The job list reloads for the selected page (10 jobs per page, fixed)