Refactored actions docs

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<Trigger>` 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).

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:[email protected]
+    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:[email protected]
+    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

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
+    <<enumeration>> 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~
+    <<interface>> 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~
+    <<interface>> 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