a61d254ff9
New specs: archer-template-library, ccp-metrics-view-restructure, compliance-list-stale-after-sidebar-edit, compliance-metric-estimated-resolution-date, compliance-remediation-display-fix, flexible-jira-ticket-creation, forecast-burndown-chart, granite-loader-export, ivanti-queue-clear-completed-fix, multi-item-jira-ticket, queue-collapsible-sections, vendor-issue-type-dropdown New steering: archer-template-gen.md Updated: migration-registration-check hook, remediation-plan-history spec, gitlab-workflow, tech, versioning steering files
123 lines
9.8 KiB
Markdown
123 lines
9.8 KiB
Markdown
# Requirements Document: Granite Loader Sheet Export
|
|
|
|
## Introduction
|
|
|
|
The STEAM Security Dashboard's Ivanti Queue already stages findings for CARD and GRANITE workflows. Once those items are worked, the next step is often submitting changes to Granite via the Team_Device Loader xlsx uploaded through SNIP XperLoad. Currently this requires manually downloading the 5MB template, finding EQUIP_INST_IDs via SNIP, and hand-filling rows — a tedious process for batches of 20+ devices.
|
|
|
|
This feature adds a "Generate Loader Sheet" action accessible from the Ivanti Queue that produces a properly formatted Team_Device Loader xlsx pre-populated with device data from the queue items, optionally enriched with EQUIP_INST_ID and other fields from the CARD API. Users select which columns they need, set bulk defaults with per-row overrides, and download a ready-to-upload xlsx.
|
|
|
|
## Glossary
|
|
|
|
- **Loader_Sheet**: The first worksheet ("Load_Sheet") in the Team_Device Loader xlsx workbook, containing the 41-column format that SNIP XperLoad accepts.
|
|
- **EQUIP_INST_ID**: The unique Granite identifier for an asset record. Required for Changes, Moves, and Deletes.
|
|
- **CARD_Enrichment**: The process of looking up an IP address in the CARD API to retrieve EQUIP_INST_ID, hostname, ASN, site, and other Granite-relevant fields.
|
|
- **Bulk_Default**: A value applied to all rows in a selected column. Can be overridden per-row.
|
|
- **Operation_Type**: One of Add, Change, Move, or Delete — determines which columns are required.
|
|
- **XperLoad**: The SNIP bulk loader tool that accepts the Team_Device Loader xlsx.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: Generate Loader Sheet Action from Ivanti Queue
|
|
|
|
**User Story:** As a security analyst, I want to generate a Granite Loader Sheet directly from my CARD/GRANITE queue items, so that I don't have to manually look up device data and fill the template by hand.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the user has one or more CARD or GRANITE queue items selected (pending or completed), THE Queue page SHALL display a "Generate Loader Sheet" action button in the floating action bar.
|
|
2. WHEN the user clicks "Generate Loader Sheet", THE system SHALL open a Loader Configuration Modal pre-populated with the IP addresses and hostnames from the selected queue items.
|
|
3. THE action SHALL be available to users in the Admin and Standard_User groups.
|
|
4. THE action SHALL support any number of selected items from 1 to 200.
|
|
5. IF no CARD or GRANITE items are selected, THE "Generate Loader Sheet" button SHALL NOT appear.
|
|
|
|
### Requirement 2: Operation Type Selection
|
|
|
|
**User Story:** As a security analyst, I want to specify what type of Granite operation I'm performing, so that the generated sheet includes the correct required columns.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Loader Configuration Modal SHALL present an Operation Type selector with options: Change, Add, Delete, Move.
|
|
2. WHEN "Change" is selected, THE system SHALL require EQUIP_INST_ID (or SITE_NAME + EQUIP_NAME) as an identifier and allow any other column as an optional change field.
|
|
3. WHEN "Add" is selected, THE system SHALL require: EQUIPMENT CLASS, SITE_NAME, EQUIP_NAME, EQUIP_TEMPLATE, EQUIP_STATUS, UDA#RESPONSIBLE ORGANIZATION#RESPONSIBLE TEAM, UDA#IP_ADDRESSING#IPV4_ADDRESS, UDA#IP_ADDRESSING#MGMT_IP_ASN.
|
|
4. WHEN "Delete" is selected, THE system SHALL require DELETE column (auto-filled with "X") and EQUIP_INST_ID (or SITE_NAME + EQUIP_NAME).
|
|
5. WHEN "Move" is selected, THE system SHALL require EQUIP_INST_ID and SITE_NAME (the new site).
|
|
6. THE default Operation Type SHALL be "Change" since queue items are typically existing assets needing updates.
|
|
|
|
### Requirement 3: Column Selection
|
|
|
|
**User Story:** As a security analyst, I want to choose which columns to include in my loader sheet, so that I only fill in what's relevant to my specific task.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Loader Configuration Modal SHALL display a list of available columns as checkboxes, grouped by category (Identification, IP Addressing, Discovery, Responsible Org, Cyber Metrics, Equipment Info, Other).
|
|
2. Columns required by the selected Operation Type SHALL be pre-checked and non-dismissable.
|
|
3. THE user SHALL be able to check additional optional columns beyond the required set.
|
|
4. THE generated xlsx SHALL only include columns that are checked (required + user-selected optional).
|
|
5. THE column order in the generated xlsx SHALL match the canonical Team_Device Loader column order (DELETE first, then SET_CONFIRMED, EQUIPMENT CLASS, EQUIP_INST_ID, etc.).
|
|
|
|
### Requirement 4: Device List with Bulk Defaults and Per-Row Overrides
|
|
|
|
**User Story:** As a security analyst, I want to set a default value for a column that applies to all rows, but override it on specific rows when devices need different values.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Loader Configuration Modal SHALL display a preview table showing all devices (rows) and selected columns.
|
|
2. FOR each selected column, THE modal SHALL provide a "Bulk Default" input above the table that sets the value for all rows in that column.
|
|
3. WHEN a Bulk Default is set or changed, ALL rows in that column that have not been individually overridden SHALL update to the new default value.
|
|
4. THE user SHALL be able to click any cell in the preview table to edit its value inline, creating a per-row override.
|
|
5. Cells with per-row overrides SHALL display a visual indicator (amber dot) distinguishing them from bulk-defaulted cells.
|
|
6. THE user SHALL be able to clear a per-row override to revert a cell back to the bulk default.
|
|
7. THE preview table SHALL be scrollable for large device lists (20+ items) while keeping column headers and the bulk default row sticky.
|
|
|
|
### Requirement 5: CARD API Enrichment
|
|
|
|
**User Story:** As a security analyst, I want to automatically look up EQUIP_INST_ID and other Granite fields from the CARD API using the device IP, so that I don't have to manually search SNIP for each device.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Loader Configuration Modal SHALL include an "Enrich from CARD" toggle/button.
|
|
2. WHEN "Enrich from CARD" is activated, THE system SHALL look up each device's IP address via the CARD API and populate available fields: EQUIP_INST_ID, EQUIP_NAME (hostname), UDA#IP_ADDRESSING#MGMT_IP_ASN, SITE_NAME (if discoverable from CARD data).
|
|
3. THE enrichment SHALL display a progress indicator while lookups are in progress.
|
|
4. IF a device IP is not found in CARD, THE system SHALL leave the EQUIP_INST_ID cell empty and display a warning indicator on that row.
|
|
5. CARD-enriched values SHALL be treated as pre-populated defaults that can still be overridden per-row.
|
|
6. THE enrichment SHALL NOT overwrite values the user has already manually entered or overridden.
|
|
7. THE system SHALL handle CARD API errors gracefully — partial enrichment is acceptable (enrich what you can, warn on failures).
|
|
8. THE CARD enrichment endpoint SHALL require the CARD API to be configured (CARD_API_URL, CARD_API_USER, CARD_API_PASS set in .env). If not configured, the "Enrich from CARD" option SHALL be hidden.
|
|
|
|
### Requirement 6: XLSX Generation and Download
|
|
|
|
**User Story:** As a security analyst, I want to download a properly formatted xlsx file that I can upload directly to SNIP XperLoad without further editing.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the user clicks "Download", THE system SHALL generate an xlsx file with a single worksheet named "Load_Sheet".
|
|
2. THE first row SHALL contain column headers matching the exact canonical Team_Device Loader column names (e.g., "UDA#RESPONSIBLE ORGANIZATION#RESPONSIBLE TEAM", not abbreviated).
|
|
3. Each subsequent row SHALL contain the device data as configured in the preview table (bulk defaults + per-row overrides).
|
|
4. THE DELETE column SHALL be auto-populated with "X" for every row when Operation Type is "Delete".
|
|
5. THE EQUIPMENT CLASS column SHALL default to "S" (Shelf) unless overridden.
|
|
6. THE generated file SHALL be named with a descriptive pattern: `Loader_{operation}_{team}_{date}.xlsx` (e.g., `Loader_Change_NTS-AEO-STEAM_2026-05-27.xlsx`).
|
|
7. THE xlsx SHALL NOT include the reference data sheets (site names, templates, etc.) — only the Load_Sheet with data. This keeps the file small and focused.
|
|
8. Empty cells SHALL remain empty (not "null" or "undefined").
|
|
|
|
### Requirement 7: Standalone Access (Outside Queue Context)
|
|
|
|
**User Story:** As a security analyst, I want to access the Loader Sheet generator without going through the queue, for cases where I have a list of devices that aren't in my queue.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. THE Loader Sheet generator SHALL be accessible as a standalone tool from the navigation drawer or a dedicated page section.
|
|
2. IN standalone mode, THE user SHALL be able to paste a list of IP addresses (one per line or comma-separated) to populate the device list.
|
|
3. IN standalone mode, THE user SHALL be able to manually add rows and fill in device identifiers (IP, hostname, or EQUIP_INST_ID).
|
|
4. ALL other functionality (operation type, column selection, bulk defaults, per-row overrides, CARD enrichment, xlsx download) SHALL work identically in standalone mode and queue-initiated mode.
|
|
|
|
### Requirement 8: Validation and Error Prevention
|
|
|
|
**User Story:** As a security analyst, I want the tool to warn me about missing required fields before I download, so that I don't upload an incomplete sheet to XperLoad.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. BEFORE generating the xlsx, THE system SHALL validate that all required columns for the selected Operation Type have values in every row.
|
|
2. IF required fields are missing, THE system SHALL highlight the empty cells in red and display a summary warning (e.g., "3 rows missing EQUIP_INST_ID").
|
|
3. THE user SHALL be able to proceed with download despite warnings (XperLoad will reject invalid rows anyway), but must explicitly acknowledge the warning.
|
|
4. THE system SHALL validate IP address format (IPv4 pattern) for the IPV4_ADDRESS column if populated.
|
|
5. THE system SHALL validate EQUIP_INST_ID is numeric when populated.
|