Scheduled notices: What happens in FOLIO?

Owned by julie.bickle
Last updated: Apr 25, 2023

==> Read on for a GROSS OVERSIMPLIFICATION (which will grow in detail over time) of the lifecycle of a scheduled patron notice. <==


1]  An item is checked out. The patron notice policy includes sending a noticed, every 2 days, after the due date.
→ When the loan is created, a notice is also created accordinlgy, scheduled, and stored in the data base (mod-circulation-storage; the related JSON schema is here).

Here's what it looks  like: 

{
  "scheduledNotices" : [ {
    "id" : "eda21607-a357-497a-ae3a-4462ea29e3c1",
    "loanId" : "1455a8c9-fae2-4c67-9231-b6477344e3ee",
    "recipientUserId" : "8ff018f3-7d76-41c6-97ae-bc258bf535d0",
    "nextRunTime" : "2022-02-21T23:43:47.048+00:00",
    "triggeringEvent" : "Due date",
    "noticeConfig" : {
      "timing" : "After",
      "recurringPeriod" : {
        "duration" : 2,
        "intervalId" : "Days"
      },
      "templateId" : "962b8d90-9700-4435-8d6e-e7af50fb2242",
      "format" : "Email",
      "sendInRealTime" : false
    },
    "metadata" : {
      "createdDate" : "2021-10-28T23:42:29.706+00:00",
      "createdByUserId" : "91db2f83-4bb8-48b7-88f1-a9e4c8c2de59",
      "updatedDate" : "2022-02-21T00:18:10.383+00:00"


  • The JSON has an attribute called sendInRealTime that will be either true or false.
    • If sendInRealTime is false, then the notice is sent in batch, once a day, at 23:59 PM (tenant-level time.)
  • The JSON also has an attribute called nextRunTime. nextRunTime is set based off of the type of notice trigger and the loan date/time. 
    • For notices that are configured to send daily (e.g., "sendInRealTime": false), nextRunTime is more of a batching indicator than a sign of when a notice will actually be delivered.


2] The scheduled notices processor runs every 2-5 minutes, and picks up all notices with nextRunTime<now  (i.e. that are in the past).

3] For each notice, all the data is downloaded (loan, user, item, etc.)
→ IF some data is missing, THEN delete the notice and post an error to the Circ Log.

Example:

In this case, the loan anonymisation process has removed the userID from the loan record, so FOLIO cannot send a notice (which is indeed expected behaviour).

Example:

In this case, an aged to lost item was returned, but there is no template to send for this particular trigger.

4] Evaluate the conditions
→ For example, IF a loan is closed, THEN the schedule notice is obsolete, and it is deleted (with no error posted to the Circ Log).
→ IF all conditions are met, THEN the notice is sent.

5] The notice is sent.

6] The scheduled notice is updated.
→ IF the notice is non-recurring (i.e. sent once), THEN the scheduled notice is deleted.
→ IF the notice is recurring, then the nextRunTime is updated according to the configuration in the patron notice policy.


More information about scheduled notices can also be found in this information box.


*** *** ***

Which modules are invovled in sending notices?

  • mod-circulation: This does the heavy lifting, containing most of the logic for scheduling notices (along with mod-feesfines):
    • Contains the code of the ScheduledNoticeHandler
    • Collects the notices from the data base
    • Builds the context for each notice (i.e. what data is to be shown for each token)
    • Sends notices to mod-notify (fetch template + send request to mod-sender)
    • Updates the notice afterwards
    • Populates the circ log
  • mod-template-engine: takes the notice context, finds the corresponding template and maps the values from the context to the template. 
  • mod-notify: Just an intermediary module, which also sends stuff like "here you can reset your password"
  • mod-sender: Also not really important; will be more important once we have different formats.
  • mod-email: Pushes emails to the SMTP server.