diff --git a/docs/actions/index.md b/docs/actions/index.md new file mode 100644 index 00000000..3bc07d16 --- /dev/null +++ b/docs/actions/index.md @@ -0,0 +1,41 @@ +# iCal4j Actions + +Reactive programming for iCalendar and vCard. + +![actions.mmd.svg](../images/actions.mmd.svg) + +## Overview + +Calendaring and scheduling applications may typically include responding to +conditions that trigger certain actions. For example, notifications must be sent for +approaching events, overdue tasks, and other conditions that require human interaction. + +Automated processes also may be triggered by similar conditions, such as updating +participation status in a calendar when a response from an attendee is received. + +This library provides a simple framework for implementing responses to trigger conditions +common to the iCalendar and vCard specifications. It uses Java Reactive Streams to implement +a resilient observer pattern that won't negatively impact performance of the observable target. + +## Trigger + +A trigger is an immutable object instance containing relevant details of a condition or +state change in an iCalendar or vCard model. A trigger includes a reference to the source +object, a URI representing the context of the object (e.g. a collection, a channel, etc.), +the type of condition/change, and a timestamp indicating when it occurred. + +Applications supporting triggers will implement the `Flow.Publisher` interface in +order to notify subscribers of model or state changes. + +## Trigger Handler + +A trigger handler implements the custom logic required to respond to changes in conditions +or state. A trigger handler is similar to an event handler, with the main difference being +each handler instance is associated with a separate trigger subscriber. + +## Trigger Subscriber + +A trigger subscriber listens for new triggers and notifies its associated trigger handler. +A trigger subscriber may be configured to control the flow of triggers depending on the +requirements of the trigger handler (e.g. handlers that take a long time to complete +may require tuning in the subscriber). diff --git a/docs/actions/workflow.md b/docs/actions/workflow.md new file mode 100644 index 00000000..32b2351f --- /dev/null +++ b/docs/actions/workflow.md @@ -0,0 +1,125 @@ +# iCal4j Actions - Workflow + +A workflow automation library using iCalendar to define workflow definitions and state. + +## Overview + +A typical workflow system supports the creation of workflow rules that control how tasks +are generated and fulfilled. + +The iCal4j Actions Workflow Engine builds on the trigger framework with support for +configurable workflows defined as iCalendar actions. + +## Time-based workflows + +Such workflow definitions can be expressed as time-based recurring actions: + + BEGIN:VCALENDAR + BEGIN:VTODO + DTSTART:20250101T080000 + DURATION:PT1H + SUMMARY:Turn on the lights + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + END:VTODO + END:VCALENDAR + +The workflow engine will generate a list of occurrences from this definition (for a specific +period of time) to schedule tasks: + + BEGIN:VCALENDAR + BEGIN:VTODO + DTSTART:20250101T080000 + DURATION:PT1H + SUMMARY:Turn on the lights + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + RECURRENCE-ID:20250101T080000 + STATUS:NEEDS-ACTION + LAST-MODIFIED:20241231T210000Z + END:VTODO + END:VCALENDAR + +A task executor may specifically check for tasks that it can complete, and update the status +accordingly: + + BEGIN:VCALENDAR + BEGIN:VTODO + DTSTART:20250101T080000 + DURATION:PT1H + SUMMARY:Turn on the lights + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + RECURRENCE-ID:20250101T080000 + STATUS:IN-PROCESS + ATTENDEE:mailto:joeb@example.com + LAST-MODIFIED:20250101T080130Z + END:VTODO + END:VCALENDAR + +_Note that the "task executor" may be a human or an automated system_ + +Once completed the task can be marked as such: + + BEGIN:VCALENDAR + BEGIN:VTODO + DTSTART:20250101T080000 + DURATION:PT1H + SUMMARY:Turn on the lights + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + RECURRENCE-ID:20250101T080000 + STATUS:COMPLETED + ATTENDEE:mailto:joeb@example.com + LAST-MODIFIED:20250101T080500Z + COMPLETED:20250101T080500Z + END:VTODO + END:VCALENDAR + +If a task is not fulfilled in the required timeframe a dedicated task reaper can close it +automatically: + + BEGIN:VCALENDAR + BEGIN:VTODO + DTSTART:20250101T080000 + DURATION:PT1H + RECURRENCE-ID:20250101T080000 + STATUS:CANCELLED + SUMMARY:Turn on the lights + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + LAST-MODIFIED:20250101T090100Z + END:VTODO + END:VCALENDAR + +This approach to workflows fulfills the following necessary features: + +* Workflow tasks are durable, in that if the workflow system has +an outage the currently active tasks are preserved. +* State of tasks is also tracked and durable. +* Timers are implicitly defined in the workflow definition such that +incomplete tasks are automatically expired. + +## Other workflow triggers + +Some workflows may not define a recurring time component, in which case they +would only be triggered by some condition: + + BEGIN:VCALENDAR + BEGIN:VTODO + DTSTART:20250101T080000 + DURATION:PT1D + SUMMARY:Approve funding request + UID:9999 + END:VTODO + END:VCALENDAR + +For such workflows the engine would recognise the conditions required to generate +a new task: + + BEGIN:VCALENDAR + BEGIN:VTODO + DTSTART:20250101T080000 + DURATION:PT1D + SUMMARY:Approve funding request + RELATED;RELTYPE=PARENT;VALUE=UID:9999 + RELATED;VALUE=UID:1234 + STATUS:NEEDS-ACTION + LAST-MODIFIED:20241231T210000Z + END:VTODO + END:VCALENDAR diff --git a/docs/images/actions.mmd b/docs/images/actions.mmd new file mode 100644 index 00000000..91ff7f8f --- /dev/null +++ b/docs/images/actions.mmd @@ -0,0 +1,44 @@ +--- +title: iCal4j Actions Framework +--- +classDiagram + direction LR + + class Trigger~T extends Serializable~ + Trigger~T~: URI context + Trigger~T~: T source + Trigger~T~: TriggerType type + Trigger~T~: Instant timestamp + + class TriggerType + <> TriggerType + TriggerType: Timer + TriggerType: Creation + TriggerType: Update + TriggerType: Deletion + + class TriggerSubscriber~T extends Serializable~ + TriggerSubscriber~T extends Serializable~: Flow.Subscription subscription + TriggerSubscriber~T extends Serializable~: TriggerHandler~T~ handler + + class TriggerHandler~T extends Serializable~ + <> TriggerHandler~T extends Serializable~ + TriggerHandler~T extends Serializable~: onTrigger(Trigger~T~ trigger) + + class WorkflowProcessor~T extends Serializable~ + WorkflowProcessor~T extends Serializable~: List~VToDo~ actions + + class TaskGenerator~T extends Serializable~ + <> TaskGenerator~T extends Serializable~ + TaskGenerator~T extends Serializable~: generate(Trigger~T~ trigger) List~VToDo~ + + class RecurringTaskGenerator + RecurringTaskGenerator: VToDo action + + class ConditionalTaskGenerator + ConditionalTaskGenerator: VToDo action + + TriggerHandler~T extends Serializable~ <|.. WorkflowProcessor~T extends Serializable~: Implements + + TaskGenerator~T extends Serializable~ <|.. RecurringTaskGenerator: Implements + TaskGenerator~T extends Serializable~ <|.. ConditionalTaskGenerator: Implements diff --git a/docs/images/actions.mmd.svg b/docs/images/actions.mmd.svg new file mode 100644 index 00000000..5e130528 --- /dev/null +++ b/docs/images/actions.mmd.svg @@ -0,0 +1 @@ +
Implements
Implements
Implements
Trigger<T extends Serializable>
URI context
T source
TriggerType type
Instant timestamp
«enumeration»
TriggerType
Timer
Creation
Update
Deletion
TriggerSubscriber<T extends Serializable>
Flow.Subscription subscription
TriggerHandler<T> handler
«interface»
TriggerHandler<T extends Serializable>
onTrigger(Trigger<T> trigger)
WorkflowProcessor<T extends Serializable>
List<VToDo> actions
«interface»
TaskGenerator<T extends Serializable>
generate(Trigger<T> trigger) : List<VToDo>
RecurringTaskGenerator
VToDo action
ConditionalTaskGenerator
VToDo action
iCal4j Actions Framework \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 7b8d23bd..1bc34217 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -113,6 +113,9 @@ nav: - Channel: command/channel.md - Store: command/store.md - Template: command/template.md + - Actions: + - Overview: actions/index.md + - Workflow: actions/workflow.md - ZoneInfo Outlook: zoneinfo-outlook.md - tzurl.org: tzurl.md - References: