How Workflow Notifications are processed
First published: 05 October 2023 (cf)
Summary
This article gives insights how Fabasoft Folio/eGov-Suite internally processes the email notification for workflow events like “New Activity Received”.
Details
Background Tasks
When a notification email for workflow activities needs to be sent, this is not done immediately but scheduled by a so-called “Background Task”, added to the “Background Tasks” property in the activity.
The background task assigned to the activity is “Send Notifications” (COOWF@1.1:DeadlineSendNotifications). This Definition for Background Tasks object defines the duration as “Short”, therefore the Automated Task with action FSCSCHEDULE@1.1001:CheckShortDeadlines is processing this kind of background tasks.
The schedule of your Automated Task FSCSCHEDULE@1.1001:CheckShortDeadlines defines in what interval these background tasks are processed. Without that Automated Task, email notification is not processed.
CheckShortDeadline processing
The Fabasoft Folio AT Service starts the CheckShortDeadlines action.
For each “Send Notification” background task, the AT Service switches context to the user that has triggered the next activity to get startable.
Example:
Mr. Huber finished his activity, so the next activity for Mrs. Miller is changed to the state “Startable”. As Mr. Huber (the predecessor) set the next activity to “Startable”, the AT Service logs on as Mr. Huber and sends the notification in Mr. Hubers context to Mrs. Miller. The AT Service also uses the domain/tendant configuration of Mr. Huber, e.g. the SMTP server configured in his tendant.
As for every background task (thus every activity) the context is switched to the specific predecessor, also permissions (ACLs) are applied for the predecessor.
In any case that the predecessor has no access to the object of the activity, a fallback situation applies:
The AT Service removes the “Send Notifications” (COOWF@1.1:DeadlineSendNotifications) background task
It schedules another background task “Send Notifications (Users Have Participated in Workflow)” (COOWF@1.1:DeadlineSendRestrictedNotifications). This background task instead of using the predecessor uses the process owner (by default).
This fallback should allow the notification to be sent also if the predecessor has no access rights to the object of the activity.
Processing the Notification Definition Configuration
The Notification Definition Configuration defines the domain/tendant defaults for email notifications. The screenshot is from the Fabasoft Folio Default Notification Definition (COOWF@1.1:DefaultNotificationDefinition), but the Fabasoft eGov-Suite or your solution may define different settings.
This definition defines for every notification type how the notification email should look:
In 1. the subject of the email is calculated. It usually contains information about the event.
In 2. an XSL Transformation object is assigned. The XSL Transformation is evaluated and generates an HTML email body.
If, for any reasons, the XSL transformation fails, the plain text field 3. Is used as a fallback.
The resulting text from 3. is shorter and not formatted as this usually results from the XSL transformation. Therefore, users may refer to “corrupted” or “truncated” email notifications.
Reasons for a failing XSL transformation can be erroneous code in the XSL file, but also permission issues on requesting object data may lead to failed XSL evaluation. Remember, that the background task is fulfilled in the context of the predecessor of the activity, or the process owner in failback situation.
Summary
Action FSCSCHEDULE@1.1001:CheckShortDeadlines needs to be scheduled by an Automated Task.
Workflow notifications create a “Send notifications” in the Background Tasks property of the activity.
The AT Service processing of each background task is done in the context of the predecessor/initiator of the now startable activity.
If in any case the predecessor has no access to the “Applied to” object of the activity, another background task “Send notifications (Users Have Participated in Workflow)” is scheduled, that is executed as the process owner user.
The XSL transformation is performed as the appropriate user as mentioned before.
If the XSL transformation fails, instead of the XSL transformation the “Notification Text” property is used as the mail body.
Debugging
See the chapter Workflow Notification Checklist to configure the AT Service and Automated Tasks at first.
To debug and analyse workflow notifications, use the app.telemetry logpool for the AT Service and filter to the CheckShortDeadline action.
Please note that in the app.telemetry request list (list in the upper area) the error column might be 0 even if errors occurs. You should click the request in the upper list and have a look to the “Error” tab on the lower list for errors like “ACCERR_DENIED”.