-
Notifications
You must be signed in to change notification settings - Fork 39
Glossary
- Workflow terms
- Deployment terms
- Workflow hierarchy terms
- Workflow definitions provided by nFlow
- Advanced terms
Workflow is a collection of tasks whose execution is orchestrated in a predefined manner. Tasks can be executed automatically (by computer) or manually (by human). Credit application process is an example of a workflow: it contains tasks starting from receiving the application and ending to granting or declining the loan.
Workflow definition represents the static structure of a workflow. This includes the order in which tasks are executed and transitions between tasks. Workflow definition is described as a Java class in nFlow. The workflow definition can be uniquely identified by it's type.
Workflow instance is a runtime instance of a workflow definition. For example, receiving credit application from a certain customer starts an instance of credit application workflow.
State is a step in a workflow, in which certain task is being executed. State has a type that determines how nFlow will handle it. The state types are:
- start: The initial state of a new workflow instance must me a start state. Workflow definition can have multiple start states, but nFlow processing will start by executing the one defined for the instance.
- manual: Manual action is required for moving to the next state. This means a call to nFlow REST or Java API to change the workflow instance state, triggered by some action outside this workflow. Manual states may have a state method that is executed when the state is entered, but it is not mandatory. After that, the workflow instance will not be processed by nFlow engine until the state is changed.
- normal: State can be executed by nFlow engine automatically according to the state method definition.
- wait: State for waiting something outside this instance to happen, including (but not limited to) child workflow instances to go to end state. When a child workflow finishes and parent is in a wait state, parent is automatically woken up by nFlow engine.
- end: State in which workflow instance can be considered finished. End states may have a state method that is executed when the state is entered, but it is not mandatory. Workflow instances in end state are eligible for nFlow maintenance (archiving and deleting) according to the maintenance settings.
Business key is defined by the creator of the workflow instance. It is not necessarily unique for each workflow instance. It may be used to link multiple workflow instances that are related to the same domain concept (e.g. account number). The business key is not used by nFlow engine.
External ID is an identifier assigned for the instance by it's creator. External IDs must be unique within the same type and executor group. nFlow uses External ID for implementing idempotent retry pattern: the first received workflow instance with a specific External ID/type/executor group combination is valid, the following workflow instances with the same External ID/type/executor group are considered duplicates.
State method or state handler method is a method with a specific signature in a workflow definition Java class. The method contains the functionality that is executed when nFlow executes a state. The state and the corresponding method have same name: e.g state createApplication is handled by method public NextAction createApplication(StateExecution e).
Workflow instance status represents the generic processing status of a workflow instance. The status is updated by nFlow engine and cannot be updated through APIs. The status is always one of the following:
- created: The workflow instance has been created but none of the states has been processed yet by the nFlow engine.
- inProgress: At least one state of the workflow has been processed by the nFlow engine, and there's more states to be processed.
- executing: The nFlow engine is currently processing one of the states of the workflow instance.
- manual: The workflow instance is in a state that requires human action. nFlow engine will not process this instance until it has been updated manually to another state and status.
- finished: The workflow instance processing has been completed and the instance is in a final state.
Every change to the workflow instance is recorded as a workflow instance action. The action tells what happened, when and what triggered the change. There are four types of instance actions:
- stateExecution: Recorded after normal, successful state execution.
- stateExecutionFailed: Recorded after normal state execution that resulted in failure.
- externalChange: Recorded when the workflow instance was updated by user, for example via REST API.
- recovery: Recorded when another nFlow node continued executing the workflow instance that was locked by another nFlow node that disappeared (crashed, lost network connection, etc) during workflow processing.
See Workflow signals
Executor group contains nFlow nodes that manage the same workflow instances and have the same workflow definitions. They share the same database and monitor each other through database stored heart beats. For example, you can have an executor group for workflows of a single application or business domain.
nFlow node is a Java process that contains at least nFlow engine module and an executor group. An active nFlow node contains workflow definitions and executors. A passive nFlow instance has no executors, but it can be used for monitoring and managing workflow instances.
Executor is a thread that processes workflow instances inside nFlow node.
Dispatcher is a thread that loads executable workflow instances from the database and assigns them to executors for processing.
Workflow instances that belong together but are executed independently by nFlow. Workflow hierarchy consists of one root workflow instance and any number of child workflow instances. For example, a shopping cart delivery workflow could start a child workflow for delivering each shopping cart item.
Root workflow is a workflow instance that can have any number of child workflows but has no parent workflow. The root workflow is not a parent workflow unless it has child workflows.
Parent workflow is a workflow instance that has one to many child workflows. Parent workflow may also be a child workflow of another workflow instance, except when it is the root workflow of the workflow hierarchy.
Child workflow is a workflow that has a parent workflow. Child workflow may also be a parent workflow, when it has child workflows of it's own. Child workflow has a link to its parent workflow and to the root workflow of the workflow hierarchy.
Bulk workflow (io.nflow.engine.workflow.curated.BulkWorkflow) is a special case of a parent workflow. You can set the concurrency for the bulk workflow, which limits the number of child workflows that are executed at the same time. This way you can avoid exhausting all executor threads by a single bulk workflow (and it's children), so you can safely add any number of child worklfows to the bulk workflow. The bulk workflow will finish when all the child workflows are finished.
Cron workflow (io.nflow.engine.workflow.curated.CronWorkflow) is an abstract base class that can be extended to implement workflows that need to wake up periodically to execute a task. The scheduling is controlled via cron state variable. After executing the task, the workflow automatically re-schedules itself.
Maintenance workflow (io.nflow.engine.workflow.curated.MaintenanceWorkflow) is a workflow supplied by nFlow that executes workflow instance clean-up tasks periodically. It extends CronWorkflow and can thus be scheduled via cron state variable. The configuration for the clean-up tasks is controlled via config state variable. An instance of the workflow can be automatically inserted at nFlow engine start-up by setting nflow.maintenance.insertWorkflowIfMissing configuration option to true. The default configuration of the clean-up can be configured via nflow.maintenance.initial.* configuration properties. You can also insert more maintenance workflows with different configurations, for example if you need to configure different clean-up for different workflow types.
See Workflow instance clean up
Workflow executor listener is a component that can be used to implement business logic common to all workflow types outside workflow state methods, for example for locking or logging purposes. Listeners must implement the WorkflowExecutorListener interface. All registered executor listeners are called by nFlow before (beforeProcessing()) and after (afterProcessing() or afterFailure()) state processing. The process() methods of the registered executor listeners form a chain that calls the next listener by default, but the implementation may break the chain and skip the state method processing by not calling the ListenerChain.next() method. The last listener in the chain is always nFlow's ProcessingExecutorListener that executes the workflow state method.