Skip to content

Report Generation State Machine

The Report Generation State Machine describes the lifecycle of asynchronous report creation within the galaxy system, modeled by the ReportStatus enumeration^[001-TODO__code.md#L7-15]. The process ensures consistency and prevents duplicate processing by maintaining strict status transitions for report records stored in the database^[001-TODO__code.md#L69-82].

States

The state machine defines three primary statuses for a report download record^[001-TODO__code.md#L7-15]:

  • RUNNING: Indicates that the report is currently being processed or waiting for data chunks^[001-TODO__code.md#L7-15].
  • SUCCESS: The final state indicating the report has been successfully generated, combined, and is ready for download^[001-TODO__code.md#L7-15].
  • FAIL: The terminal state indicating that an error occurred during generation or that the process timed out^[001-TODO__code.md#L7-15].

Workflow

Initialization

When a report request is received, the system creates a new record in the report_download_record table with the status set to RUNNING^[001-TODO__code.md#L69-82]. A check is performed using a hash of the search parameters (searchParamHash) to ensure an identical report is not already processing or completed within the cache window^[001-TODO__code.md#L35-43].

Chunk Processing and Validation

As report data is retrieved, it is processed in chunks (pages). The system accepts data updates only if the record is in the RUNNING state^[001-TODO__code.md#L56-62]. If a failure occurs during this phase (e.g., file handling errors), the status is updated to FAIL, and an error message is recorded^[001-TODO__code.md#L64-71].

Aggregation and Finalization

Once all data chunks are received (validated by comparing received page counts against expected totals), the system triggers a file combination process^[001-TODO__code.md#L63-64, L73-77]. This operation merges the individual data files into a single document (e.g., CSV or PDF)^[001-TODO__code.md#L101-123].

  • If the combination succeeds, the file path is saved, and the status is updated to SUCCESS^[001-TODO__code.md#L112-118].
  • If any exception occurs during combination, the status transitions to FAIL^[001-TODO__code.md#L113-118].
  • Upon completion (success or failure), temporary files associated with the report ID are cleaned up^[001-TODO__code.md#L118].

Failure Handling and Timeouts

The system employs a Message Queue (RabbitMQ) to handle timeouts and failures^[001-TODO__code.md#L50-51]. * If the report remains in RUNNING status for too long (exceeding the defined TTL), the message is moved to a Dead Letter Queue^[001-TODO__code.md#L50-51, L56-57]. * A listener consumes these failed messages and explicitly updates the database record status to FAIL, marking the process as terminated due to timeout^[001-TODO__code.md#L16-32].

Database Schema

The state is persisted in the vs_report_download_record table^[001-TODO__code.md#L69-82]:

  • status: Stores the current state (RUNNING, SUCCESS, FAIL)^[001-TODO__code.md#L69-82].
  • file_path: Stores the location of the generated file; this is populated only upon successful completion^[001-TODO__code.md#L69-82].
  • error_message: Records the reason for failure if the state transitions to FAIL^[001-TODO__code.md#L69-82].
  • [[Async Processing]]
  • RabbitMQ
  • [[Data Aggregation]]

Sources

^[001-TODO__code.md]