cve-dashboard/.kiro/specs/flexible-jira-ticket-creation/requirements.md

# Requirements Document

## Introduction

The STEAM Security Dashboard's Jira ticket creation flow currently requires a CVE ID and Vendor for every ticket. This locks the workflow to vulnerability-driven contexts only. In practice, the team creates Jira work items from multiple sources — Archer risk acceptance requests, email-driven tasks, and Ivanti queue items — that may not relate to a specific CVE. This feature makes CVE ID and Vendor optional, adds a source context field to track where a ticket originated, and exposes a "Create Jira Ticket" action from the Ivanti queue and Archer ticket views.

## Glossary

- **Ticket_Creation_Service**: The backend endpoint (`POST /api/jira-tickets/create-in-jira`) responsible for creating issues in Jira and storing the local record.
- **Jira_Tickets_Table**: The PostgreSQL `jira_tickets` table storing local records of Jira issues.
- **Creation_Modal**: The frontend modal dialog used to create a new Jira ticket.
- **Source_Context**: A metadata field indicating where a Jira ticket originated (e.g., `cve`, `archer`, `ivanti_queue`, `email`, `manual`).
- **Ivanti_Queue_Page**: The frontend page where users work through their Ivanti finding queue items.
- **Archer_Detail_View**: The frontend view displaying Archer ticket details.
- **Dashboard**: The STEAM Security Dashboard application.

## Requirements

### Requirement 1: Make CVE ID Optional for Ticket Creation

**User Story:** As a security analyst, I want to create Jira tickets without providing a CVE ID, so that I can track work items that originate from non-vulnerability contexts.

#### Acceptance Criteria

1. WHEN a create-ticket request is submitted without a cve_id field or with cve_id set to null, THE Ticket_Creation_Service SHALL accept the request, create the Jira issue, store the local ticket record with a NULL cve_id, and return an HTTP 201 response.
2. WHEN a create-ticket request includes a cve_id matching the pattern CVE-YYYY-NNNN+ (four-digit year, four or more digit sequence number), THE Ticket_Creation_Service SHALL store the cve_id on the local ticket record.
3. IF a create-ticket request includes a cve_id that is a non-empty string not matching the pattern CVE-YYYY-NNNN+ (four-digit year, four or more digit sequence number), THEN THE Ticket_Creation_Service SHALL reject the request with an HTTP 400 response and an error message indicating the CVE ID format is invalid.
4. IF a create-ticket request includes a cve_id that is an empty string, THEN THE Ticket_Creation_Service SHALL treat it as absent (NULL) and accept the request.
5. THE Jira_Tickets_Table SHALL allow NULL values in the cve_id column.

### Requirement 2: Make Vendor Optional for Ticket Creation

**User Story:** As a security analyst, I want to create Jira tickets without providing a Vendor, so that I can create work items for tasks that are not vendor-specific.

#### Acceptance Criteria

1. WHEN a create-ticket request is submitted with the vendor field absent, null, or an empty string, THE Ticket_Creation_Service SHALL accept the request and create the Jira issue with a NULL vendor value stored in the local ticket record.
2. WHEN a create-ticket request includes a vendor that is a non-empty string of 1 to 200 characters (after trimming whitespace), THE Ticket_Creation_Service SHALL store the trimmed vendor value on the local ticket record.
3. IF a create-ticket request includes a vendor that, after trimming, is longer than 200 characters, THEN THE Ticket_Creation_Service SHALL reject the request with a validation error indicating the vendor exceeds the maximum length.
4. THE Jira_Tickets_Table SHALL allow NULL values in the vendor column.
5. WHEN a create-ticket request is submitted without a vendor, THE Ticket_Creation_Service SHALL NOT send the vendor value to the Jira API and SHALL still create the Jira issue successfully.

### Requirement 3: Add Source Context Tracking

**User Story:** As a security analyst, I want each Jira ticket to record where it was created from, so that I can understand the origin of work items when reviewing the ticket list.

#### Acceptance Criteria

1. THE Jira_Tickets_Table SHALL include a source_context column that accepts one of: `cve`, `archer`, `ivanti_queue`, `email`, `manual`.
2. WHEN a create-ticket request does not include a source_context value, THE Ticket_Creation_Service SHALL default source_context to `manual`.
3. IF a create-ticket request includes a source_context value not in the allowed set, THEN THE Ticket_Creation_Service SHALL reject the request with an HTTP 400 response containing an error message indicating the provided value is not in the allowed set.
4. THE Ticket_Creation_Service SHALL store the source_context value on the local ticket record and return it in all GET responses that include ticket data.
5. WHEN the source_context column is added, THE Migration SHALL set existing rows to `manual` so that no ticket has a null source_context value.
6. IF an update-ticket request includes a source_context value, THEN THE Ticket_Creation_Service SHALL reject the change with an HTTP 400 response containing an error message indicating that source_context is immutable after creation.

### Requirement 4: Update the Creation Modal for Optional Fields

**User Story:** As a security analyst, I want the Create Jira Ticket modal to clearly indicate that CVE ID and Vendor are optional, so that I am not blocked from creating tickets without them.

#### Acceptance Criteria

1. THE Creation_Modal SHALL display CVE ID and Vendor fields each with a label containing the text "(optional)" and placeholder text indicating example input rather than a required value.
2. THE Creation_Modal SHALL allow submission when CVE ID and Vendor are both empty.
3. THE Creation_Modal SHALL include a Source Context selector with the options: CVE, Archer Request, Ivanti Queue, Email, Manual, and no option pre-selected by default.
4. WHEN the user selects a source context, THE Creation_Modal SHALL send the selected option's corresponding value (`cve`, `archer`, `ivanti_queue`, `email`, `manual`) in the create request payload.
5. THE Creation_Modal SHALL require Summary as a mandatory field with a maximum length of 255 characters.
6. IF the user attempts to submit with an empty Summary, THEN THE Creation_Modal SHALL prevent submission and display an inline error message indicating that Summary is required.
7. IF the user does not select a source context, THEN THE Creation_Modal SHALL omit the source_context field from the create request payload, allowing the backend to default to `manual`.

### Requirement 5: Create Jira Tickets from Ivanti Queue Context

**User Story:** As a security analyst, I want to create a Jira ticket directly from an Ivanti queue item, so that I can escalate findings to Jira without navigating away from my workflow.

#### Acceptance Criteria

1. WHILE viewing an Ivanti queue item, THE Ivanti_Queue_Page SHALL display a "Create Jira Ticket" action.
2. WHEN the user activates the "Create Jira Ticket" action on a queue item, THE Ivanti_Queue_Page SHALL open the Creation_Modal with the Summary field pre-populated with the queue item's finding_title (truncated to 255 characters) and source_context set to `ivanti_queue`.
3. WHEN the queue item has a non-empty cves_json array, THE Creation_Modal SHALL pre-populate the CVE ID field with the first element of the cves_json array.
4. IF the queue item has an empty or null cves_json value, THEN THE Creation_Modal SHALL leave the CVE ID field blank.
5. WHEN the queue item has a vendor value, THE Creation_Modal SHALL pre-populate the Vendor field with that value.
6. IF the Jira API is unavailable or returns an error when the user submits the Creation_Modal, THEN THE system SHALL display an error indication describing the failure and preserve the form field values so the user can retry without re-entering data.

### Requirement 6: Create Jira Tickets from Archer Ticket Context

**User Story:** As a security analyst, I want to create a Jira ticket from an Archer ticket view, so that I can create related Jira work items for risk acceptance exceptions.

#### Acceptance Criteria

1. WHILE viewing Archer ticket details, IF the user has editor or admin role, THEN THE Archer_Detail_View SHALL display a "Create Jira Ticket" action.
2. WHEN the user activates the "Create Jira Ticket" action on an Archer ticket, THE Archer_Detail_View SHALL open the Creation_Modal with the summary field pre-populated with the Archer ticket exc_number (e.g., "EXC-1234") and source_context set to `archer`.
3. IF the Archer ticket has an associated CVE ID, THEN THE Creation_Modal SHALL pre-populate the CVE ID field with that value.
4. IF the Archer ticket has an associated vendor, THEN THE Creation_Modal SHALL pre-populate the Vendor field with that value.
5. IF the Jira ticket creation API call fails, THEN THE Creation_Modal SHALL display an error message indicating the failure reason and SHALL retain all user-entered form data.

### Requirement 7: Database Migration for Schema Changes

**User Story:** As a database administrator, I want the schema changes applied via a migration, so that existing deployments can upgrade without data loss.

#### Acceptance Criteria

1. THE Dashboard SHALL include a migration that alters the jira_tickets table to allow NULL in the cve_id column by dropping the NOT NULL constraint.
2. THE Dashboard SHALL include a migration that alters the jira_tickets table to allow NULL in the vendor column by dropping the NOT NULL constraint.
3. THE Dashboard SHALL include a migration that adds a source_context TEXT column to the jira_tickets table with a default value of `manual`, where existing rows receive the default value upon column addition.
4. WHEN the migration runs on a database with existing jira_tickets rows, THE migration SHALL preserve all existing row values in the cve_id, vendor, ticket_key, url, summary, status, created_at, and updated_at columns without modification.
5. THE migration SHALL be idempotent — running it multiple times SHALL produce the same schema state and data as running it once, without raising errors on subsequent executions.
6. IF the jira_tickets table does not exist when the migration runs, THEN THE migration SHALL exit with an error message indicating the table is missing and no schema changes were applied.

### Requirement 8: Display Source Context in Ticket List

**User Story:** As a security analyst, I want to see the source context of each ticket in the Jira tickets list, so that I can quickly identify where work items originated.

#### Acceptance Criteria

1. THE Dashboard SHALL display the source_context value as a badge on each ticket row in the Jira tickets list view, positioned as a column between the VENDOR and SUMMARY columns.
2. IF a ticket has no source_context value (null or empty string), THEN THE Dashboard SHALL display "CVE" as the default badge text since all legacy tickets were CVE-linked.
3. THE Dashboard SHALL provide a dropdown filter for source_context values, consistent with the existing status filter dropdown, that includes an "All" option showing all tickets and one option per distinct source_context value present in the ticket data.
4. WHEN the user enters a search term in the ticket search input, THE Dashboard SHALL include the source_context value in the searchable fields alongside ticket_key, cve_id, vendor, and summary.