Concepts and terminology
Notify concepts
Gateways
A gateway is a connection to any delivery system for notifications. This could be single SMTP server, teams server or a single symphony instance, for example. Gateways are specified in a GPAL script file. You can configure multiple gateways.
Notifications
A notification is a message that you want to send somewhere. The notification has a header, a body detailing the message and a topic. The topic determines how GENESIS_NOTIFY will route the notification.
Notifications are represented by the NOTIFY table in the database. They are generic, and are capable of being sent to multiple destinations.
To create a notification in a Genesis application, all you need to do is create a NOTIFY record in the database, which is best done via the EVENT_NOTIFY_INSERT. GENESIS_NOTIFY will take care of the rest, based on the routes that are configured.
Routes
A route determines where the notification will be sent. Different gateways support different route types, but there are fields that are common to all types:
- identifier
- topic match: where the topic on a notification is a match for the topic on the route, the notification will be sent on that route
Each route type is a view across the NOTIFY_ROUTE base table, and a specific extension table that defines the fields for that view type. All the metadata-management APIs deal directly with the views, so you can think of each route type as an extension to the core NOTIFY_ROUTE table, similar to polymorphic classes in Java.
Entity types
Some route types are used for sending notifications directly to users of the application. For example, a SCREEN_ROUTE can send toast notifications directly to a user's screen, and an EMAIL_USER_ROUTE can send a notification directly to a user's email address. In contrast, an EMAIL_DISTRIBUTION_ROUTE can send a notification to email addresses that are not tied to a specific user in the system.
For routes that are used to send to application users, two fields are present on the route object: ENTITY_ID and ENTITY_ID_TYPE. These fields represent a user or set of users to deliver the notification to.
ENTITY_ID_TYPE is an enumeration with the following possible values.
| ENTITY_ID_TYPE | Description |
|---|---|
| ALL | Sends to all active users within the system. If the type is ALL, ENTITY_ID will be null. |
| SELF | Sends the notification to the user populated in the 'Sender' field of the notification. Example: Password reset notifications. If the type is SELF, ENTITY_ID will be null. |
| USER_NAME | If the type is USER_NAME, ENTITY_ID will be a single USER_NAME that will receive the notification. |
| PROFILE_NAME | If the type is PROFILE_NAME, ENTITY_ID will be the name of a PROFILE. All users that have that profile assignment will receive the notification. |
An additional value is available that matches the ENTITY_ADMIN_PERMISSION_FIELD, if it is defined in Sysdef. This is used primarily in multi-tenant systems. If using this value, notifications can be sent to everyone with visibility on a particular entity.