README

The Workflow service is a library that provides a workflow engine for managing the stage of entities in a system. It allows you to define workflows for entities and manage the stage of these entities as they progress through stages of the workflow.

How it works

The workflow model documents all conceivable stages an entity might occupy, alongside Transitions between these stages. A Transition is initiated once all requisite Conditions are met. The Workflow Tracker monitors Events, marking a Condition as fulfilled upon the occurrence of a corresponding Event. This system is designed to inform an Entity of its current stage, potential subsequent stages, and the Conditions necessary for progression. [1]

Working Example

A demo version is available under /resources/examples/entity. It contains the complete use case for a given entity to progress through all of the stages of a given workflow, including the migrations (available at /resources/examples/sql/migrations), the endpoints and the tests for this entity.

Concepts

Mainly, we have:

• Actions: Anything that can be performed to an entity.

  • e.g. sign-off first draft, approve physics content, submit analysis for review, etc.

• Events: Events represent occurrences of those actions being performed on an entity. Not necessarily all events are conditions on transitions.

  • e.g. first draft signed-off, physics content approved, analysis submitted for review, etc.

• Stages: Stages are the stages that an entity can occupy in the workflow.

  • e.g. in review, submitted to arXiv, in collaboration wide review, etc.

• Transitions: Transitions are the possible changes in stage that an entity can make, given a set of conditions. A set of transitions will compose a workflow.

  • e.g. from in review to submitted to arXiv, from submitted to arXiv to in collaboration wide review, etc.

• Conditions: Conditions are a set of events that must occur for the transition to be possible. e.g. for the transition from in review to submitted to arXiv, the conditions might be that the sign-off first draft action has been completed and the physics content has been approved.

Database schema

• WF_TRACKER: The tracker table is used to keep track of the current stage of an entity. It contains the entity id and the current stage id.

• WF_ACTION: Actions are independent of an entity type or a particular entity.

• WF_EVENT: Events represent the actions performed on a particular entity. The event table contains the entity id, the action id, and the timestamp of the event.

• WF_STAGE: Stages are also independent of an entity type or a particular entity.

• WF_TRANSITION: A transition is a change in stage that an entity type can make. The transition table contains the current stage, the target stage, and the entity type.

• WF_CONDITION: Conditions are a set of events that must occur for the transition to be possible. The condition table contains the transition id and the id of action that needs to be performed. A given transition can have multiple conditions.

Example workflow

The workflow example on the /resources/examples/sql/populate/transitions.sql file shows a workflow with 3 stages (stages defined on /resources/examples/sql/populate/stages.sql). The workflow has the following transitions:

• The entity is on the "In review" stage as soon as it is registered.
  • When an entity is registered, an event for the action "entity registered" is dispatched to the workflow service. The workflow service will then register the workflow for this entity (essentially inserting the entity id and the initial stage id on the tracker table). The workflow service will then monitor events that occur in the system. When an event occurs, the workflow service will check if the event fulfills any conditions for a transition. If all conditions of the current transition are fulfilled, the workflow service will update the entity srt to the next srt in the workflow, and the entity will start the next transition.

• When the "Approve analysis" action is performed, this corresponding event is stored on the database. The service will check if all the conditions for this transition ("In review" -> "Submitted") have been performed. Since the only condition is the event of the "Approve analysis" action being performed (and it just happened), the entity is moved to the "Submitted" stage.

• The following is an hypothetical example of an action that does not fulfill the conditions for a transition:

  • The "Update GitLab repository" action is performed.
  • The service will check if all the conditions for this transition ("Submitted" -> "Published") have been performed.
  • Since the event of the action "Mark analysis as published" has not been performed, the entity remains on the "Submitted" stage.

• From "Submitted" -> "Published" the only condition is the "Mark analysis as published" action being performed. As soon as this action is performed, the entity is moved to the "Published" stage.

• On the "Published" stage the workflow is finished, no events can occur and no transitions are possible.

Workflow branching

Let's assume now that, once the entity is on the "Published" stage, it can either become an analysis paper or a conference note. Both have different workflows already defined on the database.

On your application (not on the service!) you will simply create a new entity with the type id of the new entity type or update the entity type id of the current entity to the new entity type id. You also need to update the current stage of the entity on the tracker table to the initial stage of the new workflow.

By doing so, the entity will be on the first transition of the new workflow and the service will keep monitoring the events for the entity until it reaches the end of the new workflow.

The service doesn’t care whether an entity is a paper or a conference note. It only tracks its current stage and possible transitions. If a paper turns into a conference note, the service will keep monitoring it until the workflow is complete. Managing the entity type is the application's job, since that’s all the service needs.

Installation

1. Install the library as a dependency in your project:

    composer require glance-project/workflow-service
   

2. Run the required migrations present on /resources/examples/sql/migrations/up.sql on your database:

3. Populate the database with the necessary data. Examples of how to populate the database can be found on the /resources/examples/sql/populate folder.

4. Implement the Events interface on the events in your project. An example can be found on the /resources/examples/entity/Domain/Event folder.

5. Implement the EventDispatcher interface in your project. An example can be found on /resources/examples/entity/dependencies.php:

    EventDispatcher::class => function (ContainerInterface $container) {
        return new EventDispatcher([
            AnalysisCreated::class => [
                $container->get(RegisterAnalysisWorkflow::class),
                $container->get(SaveAction::class),
                (...)
            ],
        (...),
   

   Additionally, you need to implement the Workflow Service EventDispatcher interface in your project to dispatch events related to the workflow service:

    WorkflowEventDispatcher::class => function (ContainerInterface $container) {
        return new WorkflowEventDispatcher([
            CurrentTransitionFulfilled::class => [
                $container->get(NotifyCurrentTransitionFulfilled::class),
            ],
        ]);
    }
   

   The events that should be saved on the database must have the SaveAction class on the EventDispatcher. This will call the savePerformedAction method on the workflow service. It is there that the service will check if the event fulfills any conditions for a transition and update the entity stage if all conditions are met.

   Obs: the event for a registration of an entity needs to register the workflow for the entity. An example can be found on the /resources/examples/entity/Application/Subscriber/RegisterEntityWorkflow.php file.

References

• [1] Gabriel, J. S. S. REDESIGNING THE LHCB COLLABORATION MANAGEMENT SYSTEM: FROM A FRAMEWORK-BASED MONOLITH TO A DDD AND HEXAGONAL ARCHITECTURE-INSPIRED MODULAR MONOLITH. Federal University of Rio de Janeiro, 2024. Link