raven/devdocs/specs/core-notification.txt

# Notification specifications




############### LAST STATE OF THIS 2020-05-15 12:56:44:
	Had gone over cases and triaged them, not super fleshed out yet how it works behind the scenes but basically 
	same as v7, object save triggers notification check which puts items into and takes them out of notify event table
	recurring job processes them
	Ideally would like to see event of interest check with cached data but need to consider how many different things would be in that, could be huge 
	since I will be adding so many new notification types and they are more complex.

	client end is a list type form also each object can notify directly on demand and all users have default notification subscription
	
	No longer templating but rather using short single text string with link back to open instead and optionally send report / attachment or whatever
	also no delivery days or hours fuckery anymore, all deliveries happen all the time as appropriate to the event deliver date.  If user wants that they can configure
	their device email notification settings, not our concern anymore.
	

###########################################################
BACKEND TODO / SYSTEM FOR RAVEN


TODO: need a utility that can hash any adhoc collection of fields to work with various notify related objects
TODO: client and user notify together so any changes required to support that need to be sussed out here as much as possible in advance

CREATING NOTIFICATIONS
OBJECTS Saving an object triggers notification processing for that object:
	- in v7 biz object just submits any possible notification and later it's checked to see if anyone subscribes
		would be better to short circuit that at the biz object to stop if no events of interest
	- TODO: Every corebiz object needs at least to support created / updated with tag type as a minimum
	- type and id is submitted to eventofinterest checker (possibly also tags I think)
		AyaType, ID, eventlist,objectbefore,objectafter
		eventofinterest db table contains each type and event id
			some types are generic and apply to all corebiz for example
				i.e. tags used on an object or added
		but a workorder object would be best suited to check if a workorder is interesting event?
		monolithic class for all notifications goes through a giant switch?
	- HASH to prevent dupes
		hash all the relevant bits of a notification that make it unique then check the db table to see if that hash exists already, this is a fast way to prevent dupes
			should notify if this happens a lot maybe?
		Post delivery maybe keep a hash of the event notified on so it doesn't re-notify the exact same thing repeatedly after it was already sent
	- SUBSCRIPTION
		User's indicate subscription with record in subscription table
			Table has one row PER delivery method they want, default is APP type delivery meaning inside application
			SMTP is alternative and will deliver via email to email account or phone sms etc
			FUTURE may have alternatives here
			DUPES are ignored 
		This table is consulted for all decisions about notifications, no more eventofinterest separate table nor subscriber
		DUPES - there can be near dupes here because user may have multiple of identical but vary in only:
			Delivery method
			advancenoticetimespan (e.g. contract expiring could be one 90 days in advance to renegotiate and then one 10 days in advance for notify service to cancel etc)
			InTags - notify applies if has these tags
				empty means any
			OutTags - notify cancelled if has these tags
				empty means any
				out trumps an in, default is safer option

		CONDITION
			has optional condition fields (in v7 was guidvalue for wo status type, but we need more [investigate?])
	- DELIVERY METHODS
		no more date ranges for delivery windows
		Two methods initially
			SMTP
			APP (meaning in notifications system inside application basically the old POPUP)


TABLES WORKSHEET
v7
aNotifyEventOfInterest - subscribercount, ayatype, eventtype, "guidvalue" (extra info),created/creator/updated/updater
v8 
similar but with hash maybe for faster checking? and no created/modifed stuff, guid value would maybe be some other thing to accomodate RAVEN as it seems to deal with id of specific or maybe things like status 

v7 this is the main table where events are stored and delivered from (saved message is for quick notification)
anotifyevent - ayatype, objectid, eventtype, appliestouserid (single subscriber event), aEventDate, ASAVEDMESSAGE

v7 all subscriptions - used to process deliveries (checks for generic event to see who subscribes to it)
anotifysubscription - aNotifySubscription (aID, aUserID, aRootObjectType, aEventType, aPendingSpan, aPendingSpanUnit, aGuidValue, aCreated, aModified, aCreator,aModifier) 
v8 (timespan can be a single value, no need for units and shit in the db, just days or whatever the smallest unit is)


v7 - logs deliveries, removes any older than 7 days (that's short!?)
aNotifyDeliveryLog (aRootObjectType, aRootObjectID, aEventType,aGuidValue, aDeliveryDate, aToUserID, aDeliveryMethod, aDelivered, aErrorMessage, aToClientID )

v7 - NotifyPopup contains UI deliveries
	aNotifyPopUp (aID, aRootObjectType, aRootObjectID, aDeliveryDate, aToUserID,  aMessage ) 


V8 TABLES / OBJECTS
ALL COREBIZ
	Need CRUD check for notification events
	Need to handle check of new tags vs existing tags (delta of tags) for any notification type
	Need central common code just like biz rules check that processes notifications upon any changes
		asks notifysubscription code which notifications to process
			subscriptions code has either cached or on db lookup to see all that apply, returns an array of notifyeventtypes to be processed
		Processes each notifyeventtype that it handles or passes off to central one maybe in some cases if common code

NotifyEventType enum
	A collection of every possibly notification event

NotifyDeliveryMethod enum
	SMTP, INAPP  (more in future)

NotifySubscriptionBiz 
	handles checking for subscription relevancy and returning to biz object caller what types of notify events to process
	handles CRUD and biz rules for notifysubscriptions

NotifyEventBiz
	handles CRUD for notify events, called statically from all over the place
	puts events in the table, removes them, updates them
	Has no part in delivery except maybe to provide list to delivery object
	
NotificationBiz
	handles CRUD for (app) Notification items displayed to user in app UI
	handles flagging as seen and deleting etc

NotifyDeliveryBiz
	handle delivery and logging to notifydeliverylog
	called by generator periodically

MailMessageDelivery
	Maybe a separate object to abstract deliving emails


notifysubscription table - contains all user (and customer) subscriptions to events and delivery method, if user wants two delivery methods they have two entries here, no other table indicates events to be tracked
	note use of subscriberid (0=all of type, or specific ID) and type, this would normally be type user and the user id but covers also the case of setting up a subscription for *ALL* customers (type customer id =0 meaning all)
	also ayatype GLOBAL means that the subscription applies to events of any corebiz type 
		so for example a CreatedWithTag notification or UpdatedWithTag notification will work on any object with that tag if global or a specific type i.e. customer with that tag
	Then they can control by tag as well, intags are used to filter and include (or any if no intags), outtags filter out and trump intags
		These are also used for tag type conditions
	(aID, subscriberId, subscriberAyaType, ayatype, aEventType, advancenoticetimespan, aGuidValue, aDeliveryMethod, deliveryaddress, attachreportid, intags, outtags, HASH) 

Notifyevent table - contains all events, created by updating objects or directly in some cases and used by generator for processing as deliveries
	ayatype, objectid, eventtype, appliestouserid (single subscriber event), aEventDate, ASAVEDMESSAGE, HASH?

notifydeliverylog table - intended for troubleshooting, logs deliveries with a cap on how many records it retains.  Keeping this as a separate and distinct OPS ui thing
	(aRootObjectType, aRootObjectID, aEventType,aGuidValue, aDeliveryDate, aToUserID, aDeliveryMethod, aDelivered, aErrorMessage, aToClientID )

notification table - was popup, now the ones that show in the APP type notify delivery in the UI list; has fields for opening source and reading message and indicating read
	Note: deliberately no delivery date, if it's in this table it's delivered to user, advancenotice and genprocess handle whether it's in this table or not
	eventtype should generally be enough for message but the "message" field contains any extra info
	COLUMNS: id, userid, ayatype, objectid, eventtype (for message in ui), message

###########################################################


Important cases:
client viewing ui (was popup in v7)	https://rockfish.ayanova.com/default.htm#!/rfcaseEdit/3783



ALL EVENT TYPES INITIAL RELEASE
================================


## OLD
WorkOrderStatusChange [GENERAL] [CONDITION: WOSTATUS integer]
ContractExpiring (User notify, add more notify before time frames in cases) [GENERAL]
CSRAccepted [CUSTOMER]
CSRRejected [CUSTOMER]
NewWorkorder [CUSTOMER]
WorkorderStatusChange [CUSTOMER]  [CONDITION: WOSTATUS integer]
WorkorderClosed [CUSTOMER]
WorkorderFollowUp [CUSTOMER]
QuoteStatusChanged [CUSTOMER]  [CONDITION: QUOTESTATUS integer]
ServiceBank[Currency/Hours/Incidents]Depleted [GENERAL]
NewCSR [GENERAL]
NewMemo [PERSONAL]
QuickNotification DEPRECATED replaced by DefaultNotification below [PERSONAL]
QuoteCreatedUpdated - a bit weird, which is it created or updated? :) [GENERAL]
ScheduleMarkerImminent (will rename) [PERSONAL]
ScheduleMarkerCreated (will rename) [PERSONAL]
WorkorderItemScheduledUserCreatedUpdated [PERSONAL]
WorkorderItemScheduledUserEventImminent [PERSONAL]
WorkorderCloseByDatePassed (user) [general]
WorkorderStatusChanged (user) [GENERAL]  [CONDITION: WOSTATUS integer]
WorkorderItemOutsideServiceOverdue [general]
WorkorderItemOutsideServiceReceivedBack [GENERAL]
WorkorderItemPartRequestPartsReceived [GENERAL]


## NEW
Daily_Notify_health_check (biz and ops) [GENERAL]
Nightly_Notify_health_check (biz and ops)[GENERAL]
BackupStatus case 3786 (biz and ops)	[GENERAL]	
	(OR is this more of a general OPERATIONS notifications without choosing specific type because anyone in ops needs all)
UpcomingServiceEvent case 3725 [CUSTOMER]
WorkorderItemPartRequestCreated case 3652 [GENERAL]
ContractExpiring - Customer version in addition to User version [CUSTOMER]
WorkorderTotalExceedsThreshold - Custom notification case 1745 "the andy" [GENERAL]  [CONDITION: DOLLARTOTAL money value]
WorkOrderStatusAge "deadman" delivery if not changed before XX time period [GENERAL]

QuoteStatusAge [PERSONAL (prepared by), GENERAL]
UnitWarranyExpiry case 1361 [GENERAL]
UnitMeterReadingMultipleExceeded case 1254 [GENERAL]
DefaultNotification case 3792 used for all system and old Quick notifications [EVERYONE]
TagNotification case 3799  [CONDITION: intag, outtag, ayatype global/specific]
	(Note: this is actually just general notification if an object is created or updated and the tagging is optional)

CRUD Notifications:
	(note: tag filterable and also can select type specifically or global for any type)
	(note: differs from tag notification above in that only applies on a CHANGE of TAGS, this is an always for this op and tags are just an optional filter)
	 [CONDITION: intag, outtag, ayatype global/specific]
	ObjectCreated 
	ObjectUpdated
	ObjectDeleted

PERSONAL?  OR COVERED BY TAG FILTER ALREADY BETTER?
	WorkorderItemPartRequestPartsReceivedWhenIAmScheduled [PERSONAL]
	WorkorderItemOutsideServiceReceivedBackWhenIAmScheduled
	WorkorderItemOutsideServiceOverdueWhenIAmScheduled
	WorkorderCloseByDatePassedWhenIAmScheduled
	WorkorderStatusChangedWhenIAmScheduled [PERSONAL]


Not for certain but in the hopper to think about:
On demand ad-hoc notification case 3466 for specific object only
	not sure how to handle that, but it's a very intruiging idea, maybe it's a v.next one though?
	or maybe the tags thing will handle this?


CUSTOMER NOTIFICATIONS AND CHANGES
A bcc field for all customer notification subscriptions per case 3398

SCRATCHPAD IDEAS
=-=-=-=-=-=-=-=-=-

OVERVIEW
General
	thinking of reforming it, making all notifications very short since user can go to directly view data online anyway now, why have an overly time consuming system to format and shit
	i.e. no notification more than an SMS (160 characters but will accept more and split them up to 1600) tweet in length (280 characters)

	In cases where user wants to send an attachment / report / wiki that's another thing entirely but the message is still super short

	All notifications can be optionally filtered IN or OUT via tags on notification related object.  I.E. a workorder status change can be ignored or only see if it's tagged "region-new-york" etc

	All users can receive general notifications which come from both the system itself and from other users using the new ad-hoc send notification from any form

UI
Subscribe from the object itself's menu rather than centralized subscription setup (new)
Admin can still subscribe users on their behalf (new)

SYSTEM
-=-=-=-=-=-=-=-=-=-
EVENT_OF_INTEREST_CLASS

Internal workings:
	
	Should cache the event of interest for quick saving processing and save db getting hammered every time an object is saved



One enum list of NotificationType for any possible notification that can be processed
	Notify type is divided by actual type and then by actual delivery method
No delivery schedule anymore, let user decide how to handle at their device end, not our concern, just deliver immediately always
Notify BEfore shoudl support multiple time frames, not just one
Users not involved should not be notified, have choice on that`
	e.g. if a user is not booked on a workorder and is just a lowly tech they don't care about other workorder status changes


Types of notifications sitting in delivery queue:
	Deliver if something not changed before date "DEADMAN SWITCH"
		upon change that negates it from source object it removes the event as no longer required
	Deliver immediately regardless
		easy peasy

	





DELIVERY TYPES
	Email
	UI
	(previusly was ayanova memo, but, that's toast now, removing it)
DELIVERY FORMAT
	Custom templates for each notification set up centrally?



Hypothetical sequence of operations for designing raven notification and tie into jobs and processor

WidgetStatusChange notification
	- OnChange event triggered in [WIDGETBIZ] with before and after state of widget in question (immediately after save or delete or whatever is of interest)	
		- OnChange processor See if any users are subscribed to this event [CENTRAL_NOTIFICATION_CLASS THIS MUST BE SUPER EFFICIENT AS IT WILL BE HAMMERED] 
		(events of interest / core central event bus handler of some kind??)
			- CENTRAL_NOTIFICATION_CLASS event of interest should cache in memory events of interest and trigger cache invalidation by [EVENT_OF_INTEREST_CLASS] subscription change
		- If no then bail out early
		- If yes then compares the before and after state of the widget and the given list of events of interest and processes notifications in turn
			- Create a notification event in a table of pending notification events [CENTRAL_NOTIFICATION_CLASS]
				- See v7 schema for ideas

Deliver notifications
	- Job triggers and HandleJob is called on [CENTRAL_NOTIFICATION_CLASS] which in turn checks if any events ready to Deliver
		- Hands off NOTIFY_EVENT to deliver one at a time to a [NOTIFICATION_DELIVERY_CLASS] which in turn calls each [NOTIFICATION_DELIVERY_DELIVERY_TYPE-SMTP/POPUP/WHATEVER]


Maintenance
	- [CoreJobNotificationSweeper class] maintains the notifications tables see generator spec for thoughts









- What is "Slack"?
	- should we tie into it for notifications?