**As** a user of an OpenProject instance which is set to use project-based work package identifiers Begin of the insertion
End of the insertion Begin of the deletion
End of the deletion **I want to** use URLs with those identifiers Begin of the insertion
End of the insertion Begin of the deletion
End of the deletion **so that** I can copy those to other tools and people can from that URL see which project the work package belongs to

## Acceptance criteria

Begin of the insertion* End of the insertion Begin of the deletion -End of the deletion URLs like `/work_packages/PROJ-42` resolve to the correct work package (full view, split view, and BIM views) Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion The API v3 endpoint `GET /api/v3/work_packages/PROJ-42` resolves the work package by its semantic identifier Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Scoped queries (e.g. `WorkPackage.visible(user).find("PROJ-42")`) resolve semantic identifiers transparently Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion `WorkPackage.exists?("PROJ-42")` returns `true` when the semantic identifier exists Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Historical/aliased identifiers (from project renames) still resolve via the `work_package_semantic_aliases` table Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Numeric IDs continue to work in all URL positions — no regressions for classic mode Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion When a semantic identifier is not found, the response is a standard 404 with a work-package-specific error message (not a generic 404) Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion The API v3 work package form endpoint correctly handles semantic identifiers in parent references Begin of the insertion

* Adapt generated routes such as clipboard copy to use semantic Ids


End of the insertion Begin of the deletion

End of the deletion ## Technical notes

Begin of the insertion* End of the insertion Begin of the deletion -End of the deletion `WorkPackage::SemanticIdentifier::FinderMethods` module is included in `WorkPackage` and extended onto every AR relation, overriding `find` and `exists?` to dispatch via `semantic_id?` Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion `semantic_id?` predicate: strips whitespace, rejects non-strings and numeric strings, returns true only for `PROJECTID-SEQ` patterns — replaces Begin of the insertionFriendlyId'sEnd of the insertion Begin of the deletion FriendlyId'sEnd of the deletion `Object#friendly_id?` monkey-patch Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Resolution chain: check `identifier` column first, then fall back to `work_package_semantic_aliases` table for historical identifiers Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion `ID_ROUTE_CONSTRAINT` constant centralised in `WorkPackage::SemanticIdentifier` — single source of truth for both `config/routes.rb` and frontend `WP_ID_URL_PATTERN` Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Rails route constraint widened from `/\d+/` to accept both numeric and `PROJECTID-SEQ` patterns Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion API v3 route parameter changed from `type: Integer` to `type: String` to accept semantic IDs Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Controller and ViewComponent finders updated to use `find_by_id_or_identifier` instead of `find` Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion `RecordNotFound` raised with structured `model:`, `primary_key:`, and `id:` fields for error reporting Begin of the insertion


End of the insertion Begin of the deletion

End of the deletion ## Permissions and visibility considerations

Begin of the insertion* End of the insertion Begin of the deletion -End of the deletion **Visible to:** all users who have permission to view work packages — the identifier format in the URL does not change authorization checks Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion **Not visible when:** the semantic work package identifiers feature flag is disabled at the instance level (routes still accept the pattern but no semantic identifiers will have been assigned) Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Authorization is unchanged: `WorkPackage.visible(user)` scoping applies before identifier resolution, so users cannot access work packages they lack permission to view by guessing semantic identifiers Begin of the insertion


End of the insertion Begin of the deletion

End of the deletion ## Translation considerations

Begin of the insertion* End of the insertion Begin of the deletion -End of the deletion No new user-facing strings — this is a routing/resolution layer change Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Error messages for Begin of the insertion"not found"End of the insertion Begin of the deletion "not found"End of the deletion reuse existing `WorkPackage` record-not-found translations Begin of the insertion


End of the insertion Begin of the deletion

End of the deletion ## Out of scope

Begin of the insertion* End of the insertion Begin of the deletion -End of the deletion Generating or displaying semantic identifiers in the UI (covered by PRs #22704 and #22710) Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Allocating semantic identifiers to work packages (covered by the sequence allocation feature) Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Admin settings for enabling/configuring semantic identifier format Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Redirecting numeric URLs to semantic URLs (both forms remain valid) Begin of the insertion

* End of the insertion Begin of the deletion
-End of the deletion Sharing/copy-to-clipboard UI for semantic URLs Begin of the deletion
End of the deletion