diff --git a/code_samples/api/notifications/notification_send.php b/code_samples/api/notifications/notification_send.php index c0d4b421698..ce542c33a30 100644 --- a/code_samples/api/notifications/notification_send.php +++ b/code_samples/api/notifications/notification_send.php @@ -7,9 +7,11 @@ $subject = 'My subject'; -/** @var \Ibexa\Contracts\Notifications\Service\NotificationServiceInterface $notificationService */ -/** @var \Ibexa\Contracts\Core\Repository\UserService $userService */ -/** @var \Ibexa\Contracts\Core\Repository\PermissionResolver $permissionResolver */ +/** + * @var \Ibexa\Contracts\Notifications\Service\NotificationServiceInterface $notificationService + * @var \Ibexa\Contracts\Core\Repository\UserService $userService + * @var \Ibexa\Contracts\Core\Repository\PermissionResolver $permissionResolver + */ $notificationService->send( new SymfonyNotificationAdapter(new MyNotification($subject)), [new SymfonyRecipientAdapter(new UserRecipient($userService->loadUser($permissionResolver->getCurrentUserReference()->getUserId())))], diff --git a/docs/api/notification_channels.md b/docs/api/notification_channels.md index afbed9052ad..65bef641e70 100644 --- a/docs/api/notification_channels.md +++ b/docs/api/notification_channels.md @@ -33,17 +33,29 @@ Some events generate notifications that you can deliver to the users through one ### Available notification types -- [`Ibexa\Contracts\FormBuilder\Notifications\FormSubmitted`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-FormBuilder-Notifications-FormSubmitted.html) -- [`Ibexa\Contracts\Notifications\SystemNotification\SystemNotification`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Notifications-SystemNotification-SystemNotification.html) -- [`Ibexa\Contracts\OrderManagement\Notification\OrderStatusChange`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-OrderManagement-Notification-OrderStatusChange.html) -- [`Ibexa\Contracts\Payment\Notification\PaymentStatusChange`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Payment-Notification-PaymentStatusChange.html) -- [`Ibexa\Contracts\Shipping\Notification\ShipmentStatusChange`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Shipping-Notification-ShipmentStatusChange.html) -- [`Ibexa\Contracts\User\Notification\UserInvitation`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Notification-UserInvitation.html) -- [`Ibexa\Contracts\User\Notification\UserPasswordReset`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Notification-UserPasswordReset.html) -- [`Ibexa\Contracts\User\Notification\UserRegister`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Notification-UserRegister.html) -- `Ibexa\Share\Notification\ContentEditInvitationNotification` -- `Ibexa\Share\Notification\ContentViewInvitationNotification` -- `Ibexa\Share\Notification\ExternalParticipantContentViewInvitationNotification` +Several built-in notification types are available. +They are sent by various notifiers like event subscribers, controllers or form processors. + +| Notification type | Sent | Default recipients
— supported channels | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| +| `Ibexa\AdminUi\Notifier\Notification\`
`UserInvitation` | from the [back office invitation form]([[= user_doc =]]/user_management/manage_users/#invite-users) (notice that [the `InvitationService` doesn't send this notification](invitations.md#creating-and-sending-invitations)) | Given email address
— `actito`, `email` | +| `Ibexa\AdminUi\Notifier\Notification\`
`UserPasswordReset` | from the back office "Forgot your password?" feature form (`/user/forgot-password`) | Given email address
— `actito`, `email` | +| [`Ibexa\Contracts\FormBuilder\Notifications\`
`FormSubmitted`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-FormBuilder-Notifications-FormSubmitted.html) | on submission | [Form email notification field](customize_email_notifications.md)
— `actito`, `email` | +| [`Ibexa\Contracts\OrderManagement\Notification\`
`OrderStatusChange`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-OrderManagement-Notification-OrderStatusChange.html) | on [new order creation](/api/php_api/php_api_reference/classes/Ibexa-Contracts-OrderManagement-Event-CreateOrderEvent.html), and when an order entered a [order workflow place](configure_order_management.md#configure-order-processing-workflow) | Order owner
— `actito`, `email`, `sms` | +| [`Ibexa\Contracts\Payment\Notification\`
`PaymentStatusChange`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Payment-Notification-PaymentStatusChange.html) | when a payment entered a [payment workflow place](configure_payment.md#configure-payment-workflow) | Order owner
— `actito`, `email`, `sms` | +| [`Ibexa\Contracts\Shipping\Notification\`
`ShipmentStatusChange`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Shipping-Notification-ShipmentStatusChange.html) | when a shipment entered a [shipment workflow place](configure_shipment.md#configure-shipment-workflow) | Order owner
— `actito`, `email`, `sms` | +| [`Ibexa\Contracts\User\Notification\`
`UserInvitation`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Notification-UserInvitation.html) | from the front office invitation form (`/user/invite`) (notice that [the `InvitationService` doesn't send this notification](invitations.md#creating-and-sending-invitations)) | Given email address
— `actito`, `email` | +| [`Ibexa\Contracts\User\Notification\`
`UserPasswordReset`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Notification-UserPasswordReset.html) | from the front office "Forgot password" feature (`/user/forgot-password`) | Given email address
— `actito`, `email` | +| [`Ibexa\Contracts\User\Notification\`
`UserRegister`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Notification-UserRegister.html) | from self-registration forms `/register` and `/from-invite/register` | Registered user
— `actito`, `email` | +| `Ibexa\Share\Notification\`
`ContentEditInvitationNotification`
alias `ibexa_content_edit_invitation` | on [`createInvitation()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#methods), when participant is internal and has "edit" scope (see [Collaborative editing API](collaborative_editing_api.md)) | Given users
— `actito`, `email`, `ibexa` | +| `Ibexa\Share\Notification\`
`ContentViewInvitationNotification`
alias `ibexa_content_view_invitation` | on [`createInvitation()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#methods), when participant is internal and has "view" scope (see [Collaborative editing API](collaborative_editing_api.md)) | Given users
— `actito`, `email`, `ibexa` | +| `Ibexa\Share\Notification\`
`ExternalParticipantContentViewInvitationNotification`
alias `ibexa_external_participant_content_view_invitation` | on [`createInvitation()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#methods), when participant is external, whatever the scope (see [Collaborative editing API](collaborative_editing_api.md)) | Given email addresses
— `actito`, `email`, `ibexa` | + +Notice that `Ibexa\AdminUi\Notifier\Notification\UserInvitation` is sent by the back office and doesn't implement `Ibexa\Contracts\User\Notification\UserInvitation` which is made for front-end users. +Same for the two `UserPasswordReset` in distinct namespaces. The back office `UserPasswordReset` notification is sent by a dedicated implementation of the notifier used by the controller. + +The supported channels listed are the channels needing a specific support. +Other channels can also be used. See the channel that accept any notification types in the [Available notification channels](#available-notification-channels) table. ### Available notification channels @@ -53,19 +65,27 @@ You can list the notification channel services with the following command: php bin/console debug:container --tag=notifier.channel ``` -- `actito` - Notification forwarded as [transactional email](transactional_emails.md) -- `browser` - Notification forwarded as [flash message]([[= symfony_doc =]]/session.html#flash-messages) -- [`chat`]([[= symfony_doc =]]/notifier.html#chat-channel) - Notification forwarded to a communication platform like Slack, Microsoft Teams, or Google Chat -- [`desktop`]([[= symfony_doc =]]/notifier.html#desktop-channel) - Notification forwarded to desktop applications like JoliNotif -- [`email`]([[= symfony_doc =]]/notifier.html#email-channel) - Notification forwarded to email addresses -- `ibexa` - Notification forwarded as [back office user notifications](notifications.md#user-notifications) -- [`push`]([[= symfony_doc =]]/notifier.html#push-channel) - Notification forwarded to specific applications -- [`sms`]([[= symfony_doc =]]/notifier.html#sms-channel) - Notification forwarded to phone numbers +- Some channels don't accept the notification if it doesn't implement their specific notification interface. + These interfaces come with a method to specifically format the notification for the channel. +- Some channels accept every notification and have a default formatting if the notification doesn't implement their specific notification interface. + +| Channel | Description | Specific notification interface | Accepts any notification object | +|:---------------------------------------------------------------|-------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------| +| `actito` | Notification forwarded as [transactional email](transactional_emails.md) | `Symfony\Component\Notifier\Notification\`
`EmailNotificationInterface` | **No** | +| [`chat`]([[= symfony_doc =]]/notifier.html#chat-channel) | Notification forwarded to a communication platform like Slack, Microsoft Teams, or Google Chat | `Symfony\Component\Notifier\Notification\`
`ChatNotificationInterface` | Yes | +| [`desktop`]([[= symfony_doc =]]/notifier.html#desktop-channel) | Notification forwarded to desktop applications like JoliNotif | `Symfony\Component\Notifier\Notification\`
`DesktopNotificationInterface` | Yes | +| [`email`]([[= symfony_doc =]]/notifier.html#email-channel) | Notification forwarded to email addresses | `Symfony\Component\Notifier\Notification\`
`EmailNotificationInterface` | **No** | +| `ibexa` | Notification forwarded as [back office user notifications](notifications.md#user-notifications) | [`Ibexa\Contracts\Notifications\`
`SystemNotification\SystemNotificationInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Notifications-SystemNotification-SystemNotificationInterface.html) | **No** | +| [`push`]([[= symfony_doc =]]/notifier.html#push-channel) | Notification forwarded to specific applications | `Symfony\Component\Notifier\Notification\`
`PushNotificationInterface` | Yes | +| [`sms`]([[= symfony_doc =]]/notifier.html#sms-channel) | Notification forwarded to phone numbers | `Symfony\Component\Notifier\Notification\`
`SmsNotificationInterface` | **No** | + ### Subscriptions configuration You can find the default configuration in `config/packages/ibexa.yaml` and `config/packages/ibexa_admin_ui.yaml`. You can modify it to define your own subscriptions. +Some channels might not accept every notification type. +See the [Available notification channels](#available-notification-channels) table for channels that accept only their own interface. This page contains several examples of subscriptions configuration. !!! caution "Scopes may not merge as expected" @@ -79,6 +99,75 @@ This page contains several examples of subscriptions configuration. php bin/console ibexa:debug:config notifications.subscriptions --siteaccess= ``` + For example, the following command returns the subscription for the `admin` siteaccess. + You should see subscriptions to handle back office password reset and user invitation, and the share invitations through, at least, `email`. + + ```bash + php bin/console ibexa:debug:config notifications.subscriptions --siteaccess=admin --json | jq + ``` + ```json + { + "ibexa_content_edit_invitation": { + "channels": [ + "ibexa", + "email" + ] + }, + "ibexa_content_view_invitation": { + "channels": [ + "ibexa", + "email" + ] + }, + "ibexa_external_participant_content_view_invitation": { + "channels": [ + "email" + ] + }, + "Ibexa\\AdminUi\\Notifier\\Notification\\UserPasswordReset": { + "channels": [ + "email" + ] + }, + "Ibexa\\AdminUi\\Notifier\\Notification\\UserInvitation": { + "channels": [ + "email" + ] + }, + "Ibexa\\Contracts\\FormBuilder\\Notifications\\FormSubmitted": { + "channels": [ + "email" + ] + } + } + ``` + + The following command returns the subscriptions for the default siteaccess. + On a fresh installation, it returns the subscriptions of the `site` siteaccess. + + ```bash + php bin/console ibexa:debug:config notifications.subscriptions --json | jq + ``` + ```json + { + "Ibexa\\Contracts\\User\\Notification\\UserPasswordReset": { + "channels": [ + "email" + ] + }, + "Ibexa\\Contracts\\User\\Notification\\UserInvitation": { + "channels": [ + "email" + ] + }, + "Ibexa\\Contracts\\FormBuilder\\Notifications\\FormSubmitted": { + "channels": [ + "email" + ] + } + } + ``` + #### Subscription example The following example shows how you can deliver notifications about Commerce-related activities through Slack: @@ -107,20 +196,7 @@ The following example shows how you can deliver notifications about Commerce-rel You can define a new notification type and assign a new set of channels to it, customizing how it's delivered. It must extend the `Symfony\Component\Notifier\Notification\Notification` class and can optionally implement interfaces required by specific channels. - -- Some channels don't accept the notification if it doesn't implement their specific notification interface. - These interfaces come with a method to specifically format the notification for the channel. -- Some channels accept every notification and have a default formatting if the notification doesn't implement their specific notification interface. - -| Channel | Specific notification interface | Accepts any notification object | -|:----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------| -| `actito` | `Symfony\Component\Notifier\Notification\EmailNotificationInterface` | **No** | -| `chat` | `Symfony\Component\Notifier\Notification\ChatNotificationInterface` | Yes | -| `desktop` | `Symfony\Component\Notifier\Notification\DesktopNotificationInterface` | Yes | -| `email` | `Symfony\Component\Notifier\Notification\EmailNotificationInterface` | **No** | -| `ibexa` | [`Ibexa\Contracts\Notifications\SystemNotification\SystemNotificationInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Notifications-SystemNotification-SystemNotificationInterface.html) | **No** | -| `push` | `Symfony\Component\Notifier\Notification\PushNotificationInterface` | Yes | -| `sms` | `Symfony\Component\Notifier\Notification\SmsNotificationInterface` | **No** | +See the [Available notification channels](#available-notification-channels) table for channel-specific interfaces and channels that accept only their own interface. The `ibexa` channel sends notifications to users through their profile menu, exactly as [user notifications](notifications.md#user-notifications). The [`SystemNotificationChannel` uses the core `NotificationService`](https://github.com/ibexa/notifications/blob/v5.0.7/src/lib/SystemNotification/SystemNotificationChannel.php#L51) to do so. @@ -149,7 +225,7 @@ The [`…\Service\NotificationServiceInterface::send()`](/api/php_api/php_api_re For example, to send a notification, you often use a combination like the following: -``` php hl_lines="11-14" +``` php hl_lines="13-16" [[= include_code('code_samples/api/notifications/notification_send.php', 2) =]] ``` diff --git a/docs/content_management/collaborative_editing/collaborative_editing_api.md b/docs/content_management/collaborative_editing/collaborative_editing_api.md index f316ce2197b..b54c1c2a8bf 100644 --- a/docs/content_management/collaborative_editing/collaborative_editing_api.md +++ b/docs/content_management/collaborative_editing/collaborative_editing_api.md @@ -72,6 +72,16 @@ You can add participant to the collaboration session with [`SessionService::addP [[= include_code('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 81, 93, remove_indent=True) =]] ``` +Participants can be internal (based on an existing user) or external (on an email address): + +[`InternalParticipantCreateStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-Participant-InternalParticipantCreateStruct.html#properties) +[`ExternalParticipantCreateStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-Participant-ExternalParticipantCreateStruct.html#properties) + +Two scopes are available: + +- [`ContentSessionScope::EDIT`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Share-Collaboration-ContentSessionScope.html#constant_EDIT) +- [`ContentSessionScope::VIEW`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Share-Collaboration-ContentSessionScope.html#constant_VIEW) + ### Get and update participant You can update participant added to the collaboration session with [`SessionService::updateParticipant()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_updateParticipant): diff --git a/docs/permissions/permission_use_cases.md b/docs/permissions/permission_use_cases.md index c29c5b32ea3..277c5498f99 100644 --- a/docs/permissions/permission_use_cases.md +++ b/docs/permissions/permission_use_cases.md @@ -164,7 +164,7 @@ With limitations, you can configure whether permissions apply to Tags, product c ## Register users -To allow anonymous users to register through the `/register` route, grant the `user/register` policy to the Anonymous user group. +To allow anonymous users to register through the `/register` or `/from-invite/register` routes, grant, to the Anonymous role, the `user/register` policy and the `content/create` policy limited to the User content type and some user groups. ## Admin diff --git a/docs/users/invitations.md b/docs/users/invitations.md index ddcebdd860c..7d5c94fef50 100644 --- a/docs/users/invitations.md +++ b/docs/users/invitations.md @@ -9,13 +9,13 @@ You can send invitations to individual users or in bulk. ## Roles and policies -To invite other members to the site or the back office, a user needs to have the `User:Invite` permission added to their role. +To invite other members to the site or the back office, a user needs to have the `user/invite` permission added to their role. You can limit the ability to invite other members to specific user groups, such as Editors, or to the specific roles within the group, for example: Admin, Buyer. ## Creating and sending invitations Invitations are created with [InvitationService](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Invitation-InvitationService.html), but sending them requires additional setup. -[[= product_name =]] provides you with `Ibexa\User\Invitation\MailSender` implementation of `InvitationSender` interface for sending invitations via email. +[[= product_name =]] provides you with `Ibexa\User\Invitation\MailSender` implementation of [`InvitationSender`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-User-Invitation-InvitationSender.html) interface for sending invitations via email. If you want to send invitations through different channels, you need to create a custom setup. ## Invitation and registration form templates