Important

You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Notification Alerts¶

You may sometimes need to log the errors that arise during the sync process when synchronizing data and notify user or system administrator about such an error in order to perform steps for issue resolution.

All the alerts are stored in database and are available in the application back-office UI or via CLI command.

Implementation details¶

The class that represents a notification alert for your resource type must implement NotificationAlertInterface.

You need to register your own notification alert manager to work with a particular integration and resource type in order to add your notification alerts. As an example, please see NotificationAlertManager.

The NotificationAlertManager should be registered as a service with the source type name and resource name, as illustrated below:

acme_demo.your_notification_alert_manager:
    class: Oro\Bundle\NotificationBundle\NotificationAlert\NotificationAlertManager
    arguments:
        - '<SourceTypeName>'
        - '<ResourceTypeName>'
        - '@doctrine'
        - '@oro_security.token_accessor'

By using the acme_demo.your_notification_alert_manager service and the notification alert object(s), you can log the alert(s) in the code and have them displayed in the datagrid and, for example, implement them as flash message notification(s).

If the alert is fixed or is no longer relevant, there are different ways to clear it:

in code, using resolve functions of the alert manager;

in UI, in the Notification Alerts datagrid via delete or mass-delete actions;

using the oro:notification:alerts:cleanup console command that deletes notification alert records.

Viewing alerts in back-office¶

To view the datagrid that displays the list of all occurred notification alerts, navigate to System > Alerts in the back-office UI.

Alert entity datagrid columns:

Column name	Data type	Description
ID	GUID	Unique alert identifier, appears in logs for further alert cause investigation or reporting
CREATED AT	DateTime	The date and time when an alert has been logged
UPDATED AT	DateTime	The date and time when an alert has been updated Note The cause of update may be alert resolving, subsequent occurrence of the same alert.
USER	relation	The value is optional. Shows the user first name and last name who has performed the operation
MESSAGE	text	The value is optional. Error or exception message that describes the cause of the occurred alert
SOURCE	string	The source of the alert, usually related to bundle name, integration name, CLI command, MQ job, e.g. MicrosoftSync, GoogleIntegration, price-lists:recalculation, etc. Note It is recommended to name the source according to the Bundle name that is responsible for the integration\|job implementation, for example: MycrosoftSync, GoogleIntegration, Pricing
RESOURCE	string	The resource being involved during integration\|job execution Note One source may be responsible for several Resources, example MicrosoftSync <> Calendar Event entity, MicrosoftSync <> Tasks entity. Note It is recommended to name the resource according to the entity name or use FQCN, that is related to the integration or job that caused an alert, e.g. Tasks, Calendars, Calendar Event, User, PriceList
ALERT TYPE	string	Specifies the type of the alert, e.g. auth, sync, etc. For example, depending on Alert Type the appropriate type (Error, Warning, Notice) of the flash message can be shown for the particular user
OPERATION	string	The value is optional. Describes the operation that caused an alert e.g. for integrations case the value can be import, export, etc.
STEP	string	The value is optional. Describes any logical part of the operation, e.g. get_list, get, map, save, load, etc. Usually is used to specify the alert cause more precisely for further issue investigation
ITEM ID	integer	The value is optional. The identifier of the specific resource (Entity) item, e.g. Task id or CalendarEvent id, etc. Note The value can be empty, for example the case when Exception triggered on the step when entity id is not defined
EXTERNAL ID	string	The value is optional. The identifier of the specific resource item from external application, for example the Task id or CalendarEvent id of the remote service, e.g. Microsoft Calendar or Task
RESOLVED	bool	Determines if the alert has been resolved, for example the alert can be raised during the first sync attempt due to timeout or connection issues and resolved later after retry, even without involving the administrator

Manipulating alerts in CLI¶

List alerts¶

To list notification alert use oro:notification:alerts:list command.

By default the last 20 alert records are shown, use --page and --per-page command options to paginate.

The option --summary allows to display alerts in statistical mode - all the record will be grouped by source, resource and alert type with amount of similar alerts.

By default only not resolved alerts are involved in listing, to include the resolved ones into listing the option --resolved should be used for such purposes.

It is also possible to filter records by one or multiple filters, for example the --source-type, --resource-type, --alert-type, --current-user and --current-organization.

The result of the command execution will be the full or summary list of notification alerts.

$ php bin/console --env=prod oro:notification:alerts:list --resource-type calendar

+--------+------------------+------------------+---------+----------------------------------+---------------+---------------+------------+-----------+------+---------+--------------+----------+
| Id     | Created At       | Updated At       | User    | Message                          | Source        | Resource      | Alert Type | Operation | Step | Item Id | External Id  | Resolved |
+--------+------------------+------------------+---------+----------------------------------+---------------+---------------+------------+-----------+------+---------+--------------+----------+
| c2f777 | 7/17/21, 7:04 PM | 7/17/21, 7:04 PM | charlie | Calendar event data has no type. | MyIntegration | calendar      | sync       | import    | map  |         | d2f8165b49f3 | No       |
| c2f999 | 8/23/21, 7:04 PM | 8/23/21, 7:04 PM | admin   | Calendar event data has no type. | MyIntegration | calendar      | sync       | import    | map  |         | d2f8165b49f5 | No       |
| c2f833 | 7/18/21, 7:04 PM | 7/18/21, 7:04 PM | charlie | Calendar event data has no type. | MyIntegration | calendar      | auth       | import    | map  |         | d2f8165b49f4 | No       |
+--------+------------------+------------------+---------+----------------------------------+---------------+---------------+------------+-----------+------+---------+--------------+----------+

$ php bin/console --env=prod oro:notification:alerts:list --resource-type calendar --summary

+---------------+---------------+------------+---------------+
| Source        | Resource      | Alert Type | Alerts Amount |
+---------------+---------------+------------+---------------+
| MyIntegration | calendar      | sync       | 2             |
| MyIntegration | calendar      | auth       | 1             |
+---------------+---------------+------------+---------------+

Cleanup alerts¶

To cleanup notification alert(s) use oro:notification:alerts:cleanup command.

All the filters of the oro:notification:alerts:list are relevant for the cleanup command as well.

Additionally the --id filter is available if it is required to delete single alert record by its identifier.

When command oro:notification:alerts:cleanup is executed without any filters all alerts are deleted (an appropriate action confirmation will be asked).

Automatic outdated alerts cleanup¶

The command oro:cron:notification:alerts:cleanup allows to cleanup outdated (older than 30 days) and resolved notification alerts. It is scheduled for execution once a week at 00:00 on Sunday.