The main purpose is to make a deduplicating identifier available for
interaction with integrations. We want to start using it for the integration
with XWiki, but the underlying problem occurs regularly in integrations:
It's possible for an OP instance to integrate with more than one XWiki instance.
Vice versa it's also possible for one XWiki to integrate with multiple OPs.
When this happens, API calls like "show me wiki pages that point to work package 123"
become ambiguous, because WP 123 might exist on multiple OpenProject instances. Thus it
makes sense to have a global identifier for the OpenProject instance. Different identifiers
look good and unique at first, but they are not working well in detail:
* Base URL (e.g. https://openproject.example.com): Some instances are available via more than one URL,
e.g. inside cluster vs. outside cluster.
* OAuth client ID: Usually not known to other party, and not guaranteed to be unique, because multiple
authentication providers could be involved
Hence we decided to use a uniquely generated ID and expose it in a way that doesn't require additional configuration
by the users, but can be automatically discovered during integration setup.
Replace the conditional `semanticId` API field with `displayId` which is
always present in work package responses. In semantic mode it returns the
project-based identifier (e.g. "PROJ-42"), in classic mode it returns the
numeric ID as a string. This gives API consumers (frontend, mobile) a
single field to read without conditional logic.
- Add `WorkPackage#display_id` method that encapsulates the mode check
- Update both representers (JSON and SQL) to render `displayId` unconditionally
- Update OpenAPI schema documentation
Adds the computed semanticId property to the HAL representer,
SQL collection representer, and schema representer. The property is
gated behind the semantic_work_package_ids feature flag and returns the
value from WorkPackage#identifier. Includes OpenAPI docs
and the translation key for the schema name.
We only used to mention the APIv3 and the BCF API and even then
some parts of the text were clearly written as if only APIv3 existed.
This has been updated to mention the other kinds of APIs currently offered by OpenProject.
Oliver Günther