Support retrieval of workflow run metadata by instance ID

[nscuro]

Description

Supports retrieval of workflow run metadata by instance ID.

Enables API clients to query run metadata by a given workflow instance ID.

This enables basic status reporting of asynchronous tasks (e.g. vuln datasource mirroring) in the admin UI. "Singleton" workflows will have a static instance ID that the frontend can query for. As long as the new endpoint returns run metadata, the UI can display an "in progress" spinner, and prevent users from triggering the task redundantly.

Addressed Issue

N/A

Additional Details

https://github.com/DependencyTrack/hyades-apiserver/blob/main/dex/docs/PATTERNS.md#singletons

Checklist

• I have read and understand the contributing guidelines
• This PR fixes a defect, and I have provided tests to verify that the fix is effective
• This PR implements an enhancement, and I have provided tests to verify that it works as intended
• This PR introduces changes to the database model, and I have updated the migration changelog accordingly
• This PR introduces new or alters existing behavior, and I have updated the documentation accordingly

[Copilot]

Pull request overview

This PR adds support for retrieving workflow run metadata by workflow instance ID, enabling API clients to query the status of singleton workflows for use in the admin UI. The PR also refactors existing method names for better clarity.

Changes:

• Added new getRunMetadataByInstanceId method to DexEngine API and implementation that returns metadata only for non-terminal runs
• Renamed getRun to getRunById and getRunMetadata to getRunMetadataById for consistency
• Consolidated OpenAPI schema by replacing list-workflow-runs-response-item.yaml with the more general workflow-run-metadata.yaml

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
dex/engine-api/src/main/java/org/dependencytrack/dex/engine/api/DexEngine.java	Added new interface method getRunMetadataByInstanceId and renamed existing methods for consistency
dex/engine/src/main/java/org/dependencytrack/dex/engine/DexEngineImpl.java	Implemented new method and renamed existing methods to match interface changes
dex/engine/src/main/java/org/dependencytrack/dex/engine/persistence/WorkflowDao.java	Added DAO method to query workflow runs by instance ID with non-terminal status filter
dex/engine/src/test/java/org/dependencytrack/dex/engine/DexEngineImplTest.java	Updated test method calls to use renamed methods and added comprehensive tests for new functionality
dex/testing/src/main/java/org/dependencytrack/dex/testing/WorkflowTestExtension.java	Updated test utility to use renamed methods
apiserver/src/main/java/org/dependencytrack/resources/v2/WorkflowsResource.java	Implemented new endpoint and extracted conversion logic to reusable helper method
apiserver/src/test/java/org/dependencytrack/resources/v2/WorkflowsResourceTest.java	Added tests for new endpoint covering success and 404 scenarios
api/src/main/openapi/openapi.yaml	Added new API endpoint path reference
api/src/main/openapi/paths/workflow-instances__id_.yaml	Defined OpenAPI specification for new endpoint with clear documentation
api/src/main/openapi/components/schemas/workflow-run-metadata.yaml	Created reusable schema for workflow run metadata
api/src/main/openapi/components/schemas/list-workflow-runs-response.yaml	Updated to reference consolidated schema

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ -0.02% (target: -1.00%)	✅ 93.33% (target: 70.00%)

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (a5ed1d9)	36442	30546	83.82%
Head commit (e5e6abb)	36423 (-19)	30521 (-25)	83.80% (-0.02%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#1668)	45	42	93.33%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.