[SE-641] Allow to create mentions via the API by judithroth · Pull Request #26028 · opf/openproject

judithroth · 2026-10-14T14:04:52Z

This is best reviewed commit by commit :)

Ticket

https://community.openproject.org/wp/SE-641

What are you trying to accomplish?

Allow to create notifications (e.g. when a user is created in a document) via the API. So far this only uses a email notification; in app notifications will follow in a separate PR, as well as using this new API endpoint.

Screenshots

What approach did you choose and why?

Allow to create notifications via the API because

There will be deep changes to how we save documents and their journals in the future.
We can not for sure determine the user who created the mention from the document's journal entry when multiple users are editing a document simultaneously.
We don't want to carry over the information which user created the mention via the block properties and markdown export, because this could be manipulated by users. It also carries some risks when mentions are copied (could still hold wrong mentioner) or dragged.
This opens up the possibility to have mentions from external sources which use block note extensions in the future (if we want that)

AI involvement

Collaborative – AI generated a substantial part of the code; I reviewed and understand every line.

Merge checklist

Added/updated tests
Added/updated documentation in Lookbook (patterns, previews, etc)
Tested major browsers (Chrome, Firefox, Edge, ...)

Copilot

🟡 Changes recommended

The new public API operation is missing from the OpenAPI specification.

1 open finding

Document new POST /api/v3/notifications operation in OpenAPI · New

What changed in this PR

Adds API-driven document mentions, including email delivery, BlockNote support, validation, and notification lifecycle handling.

Changes:

Adds POST /api/v3/notifications for document mentions.
Adds mention rendering, emails, preferences, and cleanup.
Adds frontend/editor support and comprehensive tests.

File	Description
`app/contracts/notifications/create_mention_from_api_contract.rb`	Validates API mentions and permissions.
`app/models/notification_setting.rb`	Registers the enabled-settings scope.
`app/models/notification_settings/scopes/enabled_for.rb`	Resolves enabled project settings.
`app/services/notifications/create_from_api_service.rb`	Creates API mention notifications.
`app/services/notifications/create_from_model_service.rb`	Shares strategy lookup and tightens cleanup scope.
`config/locales/en.yml`	Adds validation messages.
`extensions/op-blocknote-hocuspocus/src/extensions/openProjectApi.ts`	Supports mention serialization.
`extensions/op-blocknote-hocuspocus/test/extensions/openProjectApi.test.ts`	Tests mention serialization.
`frontend/src/react/components/OpBlockNoteEditor.tsx`	Enables user mentions in BlockNote.
`lib/api/v3/notifications/notification_created_representer.rb`	Adds reduced creation response.
`lib/api/v3/notifications/notifications_api.rb`	Adds the creation endpoint.
`modules/documents/app/mailers/documents_mailer.rb`	Sends document mention emails.
`modules/documents/app/models/document.rb`	Cleans up associated notifications.
`modules/documents/app/services/notifications/create_from_model_service/document_strategy.rb`	Opts documents into API mentions.
`modules/documents/app/services/notifications/mail_service/document_strategy.rb`	Dispatches mention emails.
`modules/documents/app/views/documents_mailer/mentioned.html.erb`	Adds HTML email content.
`modules/documents/app/views/documents_mailer/mentioned.text.erb`	Adds text email content.
`modules/documents/config/locales/en.yml`	Adds email translations.
`modules/documents/spec/mailers/documents_mailer_spec.rb`	Tests mention emails.
`modules/documents/spec/models/document_spec.rb`	Tests notification cleanup.
`modules/documents/spec/services/notifications/create_from_model_service/document_strategy_spec.rb`	Tests document strategy behavior.
`modules/documents/spec/services/notifications/mail_service_spec.rb`	Tests mail dispatch preferences.
`spec/contracts/notifications/create_mention_from_api_contract_spec.rb`	Tests mention validation.
`spec/lib/api/v3/notifications/notification_created_representer_rendering_spec.rb`	Tests reduced representation.
`spec/mailers/previews/documents_mailer_preview.rb`	Adds mail previews.
`spec/requests/api/v3/notifications/notifications_api_create_resource_spec.rb`	Tests endpoint behavior.
`spec/services/notifications/create_from_api_service_spec.rb`	Tests notification creation service.
`spec/services/notifications/create_from_model_service_comment_spec.rb`	Tests scoped notification cleanup.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

github-actions · 2026-10-14T15:12:56Z

Warning

Flaky specs

rspec ./spec/features/work_packages/table/inline_create/create_work_packages_spec.rb[1:1:1:1:1]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #26028, linked for reference only):

- `rspec ./spec/features/work_packages/table/inline_create/create_work_packages_spec.rb[1:1:1:1:1]`

Treat this as a standalone task, unrelated to PR #26028. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #26028 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @judithroth to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @judithroth, and request a review from @judithroth.
On every commit, set @judithroth as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.

judithroth · 2026-10-20T09:00:23Z

+        include API::Decorators::LinkedResource
+        extend API::Decorators::PolymorphicResource
+
+        property :id


The id behind exposing this is to enable:

deleting the notification if the user removes the mention right after creating it (e.g. some seconds later)

being able to somehow use this as an "anchor", so when we show documents in the notification center in a split screen, we can scroll to where the user was mentioned.

Both is not implemented yet but would be really nice.

brunopagno

From a code standpoint this looks good. This opens up the API to do cool stuff 😁

BUT... I catch myself thinking if we need extra gates to protect client applications from sending "ghost" notifications, or from sending multiple notifications for a single event.

Initial brain dump~ we could do something like enqueue a job to send the notification with a delay (30 secs? something short enough) and then the job checks the state of the data and decides if we discard or actually send the notification. I don't know enough of this area of the codebase to make a better informed decision.

In any case, I think this is the right path. Approved because awesome 🎉

brunopagno · 2026-10-20T11:15:37Z

+      def enabled_for(reason, project)
+        where(reason => true)
+          .applicable(project)
+      end


These auto injected things kinda get me off guard every time.

My feeling is that it would be nicer to have this simple scope explicit on the class it's being used. Unless it's used in multiple places, then I guess extracting into a concern kidna makes sense.

Still no action necessary, just me preferring explicitness.

brunopagno · 2026-10-20T11:19:07Z

+      @user = user
+    end
+
+    # @param reason [String, Symbol] has to be "mentioned"


If the parameter has to be the same constant value, do we need it?

… in documents https://community.openproject.org/wp/SE-641

…otification in the API https://community.openproject.org/wp/SE-641

https://community.openproject.org/wp/SE-641

judithroth self-assigned this Oct 14, 2026

judithroth requested a balanced review from Copilot October 14, 2026 14:04

judithroth added the Passion time label Oct 14, 2026

github-actions Bot added the ai: Collaborative 💻 AI generated a substantial part of the code; A human reviewed and understands every line. label Oct 14, 2026

Copilot started reviewing on behalf of judithroth October 14, 2026 14:05

View session

Copilot AI reviewed Oct 14, 2026

View reviewed changes

Comment thread lib/api/v3/notifications/notifications_api.rb

github-advanced-security Bot found potential problems Oct 14, 2026

View reviewed changes

Comment thread lib/api/v3/notifications/notifications_api.rb Fixed

judithroth force-pushed the feature/se-641-mention-users-in-documents-backend-part-1 branch from 2ced463 to 56066dc Compare October 14, 2026 14:17

judithroth force-pushed the feature/se-641-mention-users-in-documents-backend-part-1 branch 2 times, most recently from 4c859f3 to e94a426 Compare October 15, 2026 09:58

judithroth marked this pull request as ready for review October 15, 2026 10:05

judithroth requested a review from a team October 15, 2026 10:57

This was referenced Oct 16, 2026

[SE-641] @ mention users in documents #26018

Open

[SE-641] Mention users in documents #25917

Draft

judithroth force-pushed the feature/se-641-mention-users-in-documents-backend-part-1 branch from e94a426 to c1cdaf7 Compare October 16, 2026 10:54

ihordubas99 added this pull request to stack #26090 October 16, 2026 11:03

judithroth commented Oct 20, 2026

View reviewed changes

brunopagno approved these changes Oct 20, 2026

View reviewed changes

judithroth added 4 commits October 23, 2026 16:27

[SE-641] Add APIv3 endpoint for creating notifications about mentions…

ca5059c

… in documents https://community.openproject.org/wp/SE-641

[SE-641] Return reduced representer after successfull creation of a n…

2e39cd3

…otification in the API https://community.openproject.org/wp/SE-641

[SE-641] Send email notification for mention in document

9e26ebf

https://community.openproject.org/wp/SE-641

[SE-641] Document new API endpoints for creating notifications

2392f56

https://community.openproject.org/wp/SE-641

ihordubas99 force-pushed the feature/se-641-mention-users-in-documents-backend-part-1 branch from c1cdaf7 to 2392f56 Compare October 23, 2026 13:32

Navigation Menu

Repository navigation

[SE-641] Allow to create mentions via the API - #26028

[SE-641] Allow to create mentions via the API#26028
judithroth wants to merge 4 commits into
devfrom
feature/se-641-mention-users-in-documents-backend-part-1

judithroth commented Oct 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

judithroth Oct 20, 2026 •

edited

Loading

Uh oh!

brunopagno left a comment

Uh oh!

brunopagno Oct 20, 2026

Uh oh!

brunopagno Oct 20, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

Conversation

judithroth commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Ticket

What are you trying to accomplish?

Screenshots

What approach did you choose and why?

AI involvement

Merge checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

judithroth Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brunopagno left a comment

Choose a reason for hiding this comment

Uh oh!

brunopagno Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

brunopagno Oct 20, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

judithroth commented Oct 14, 2026 •

edited

Loading

judithroth Oct 20, 2026 •

edited

Loading