Skip to content

Commit

Permalink
docu
Browse files Browse the repository at this point in the history 
Issue #823
  • Loading branch information
@rsoika
rsoika committed Sep 1, 2024
1 parent f7f55ee commit 0760741
Show file tree
Hide file tree
Showing 6 changed files with 55 additions and 45 deletions.
20 changes: 10 additions & 10 deletions imixs-workflow-core/src/main/java/org/imixs/workflow/WorkflowManager.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,14 @@ public interface WorkflowManager {
/**
* This method processes a workItem. The workItem needs at least provide the
* valid attributes $taskID and $EventID (integer values) to identify the
* current processEntity the workItem belongs to and the concrete activtyEntity
* which should be processed by the wokflowManager implementation. If the
* current processEntity the workItem belongs to and the concrete BPMN event
* which should be processed by the WorkflowManager implementation. If the
* workItem is new the method creates a new instance for the corresponding
* process.
* <p>
* The method is responsible to persist the workItem after successfully
* processing. The method returns the workItem with additional workflow
* informations defined by the workfowManager Implementation.
* information defined by the WorkflowManager Implementation.
* <p>
* The Method throws an InvalidWorkitemException if the provided workItem is
* invalid or the provided attributes $taskID and $EventID (integer) did not
Expand All @@ -80,22 +80,22 @@ public ItemCollection processWorkItem(ItemCollection workitem)
throws AccessDeniedException, ProcessingErrorException, PluginException, ModelException;

/**
* returns a workItem by its uniuqeID ($uniqueID)
* returns a workItem by its uniqueID ($uniqueID)
*
* @param uniqueid
* @param uniqueID
* @return WorkItem
*
*/
public ItemCollection getWorkItem(String uniqueid);
public ItemCollection getWorkItem(String uniqueID);

/**
* The method removes the provide Workitem form the persistence unit managed by
* The method removes a Workitem form the persistence unit managed by
* the WorkflowManager implementation.
*
* The Method throws an InvalidWorkitemException if the provided Workitem is
* invalid.
* The method throws an AccessDeniedException if the work item cannot be removed
* due to its state or user permissions.
*
* @param uniqueid of the WorkItem to be removed
* @param uniqueId of the WorkItem to be removed
* @throws AccessDeniedException
*/
public void removeWorkItem(ItemCollection workitem) throws AccessDeniedException;
Expand Down
47 changes: 23 additions & 24 deletions src/site/markdown/core/model.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,20 @@
# The Imixs ModelManager
# The BPMN ModelManager

The Imixs `ModelManager` separates the BPMN process definition from the Workflow implementation. The interface provides methods to manager BPMN Model instances and navigate through a Workflow Model with its different elements. A workflow model has a unique version ID which allows to uniquely identify a BPMN model inside one Workflow Management System. The Model Version is provided by a workflow instance in the item `$modelVersion`.
The class `org.imixs.workflow.ModelManager` provides methods to access and manage instances of a *BPMN 2.0 Model* and navigate through a Model with its different elements. A *BPMN 2.0 Model* instance is uniquely identified by its version ID. A workitem provides the version ID of a model in the mandatory item `$modelVersion`.

An Imixs BPMN Model can be defined using the [Imixs-BPMN modeling tool](../modelling/index.html).

<img src="../images/modelling/bpmn_screen_00.png"/>
The BPMN ModelManager operates directly on the class `org.openbpmn.bpmn.BPMNModel` from the [Open-BPMN Meta model](https://github.com/imixs/open-bpmn/tree/master/open-bpmn.metamodel).
A BPMNModel instance allows full access to a BPMN 2.0 model and provides methods to navigate through a BPMN model. The BPMN `ModelManager` can be used in any custom Java implementation of Imixs-Workflow. Find further information at the [Open-BPMN Meta Project on Github](https://github.com/imixs/open-bpmn/tree/master/open-bpmn.metamodel).



## The ModelManager Interface
The interface `org.imixs.workflow.ModelManager` manage instances of a `BPMNModel` and is used by the [WorkflowKernel](workflowkernel.html) to access model information during the processing life cycle .

The Interface defines the following methods:

|Method | Description |
|----------------------------|---------------------------|
|getModel(version) | Returns a Model by version. The method throws a ModelException in case the model version did not exits.|
|addModel(BPMNModel) | Adds a new Model to the ModelManager.|
|removeModel(version) | Removes a Model from the ModelManager.|
|loadDefinition(workitem) | Returns the BPMN Definition entity associated with a given workitem.|
|loadProcess(workitem) | Returns the BPMN Process entity associated with a given workitem. |
|loadTask(workitem) | Returns the BPMN Task entity associated with a given workitem.|
|loadEvent(workitem) | Returns the BPMN Event entity associated with a given workitem.|
|nextModelElement(event, workitem) | Returns the next BPMN Flow Entity followed by a given Event Entity.|
## The BPMNModel

An Imixs BPMN Model can be defined using the [Imixs-BPMN modeling tool](../modelling/index.html).

<img src="../images/modelling/bpmn_screen_00.png"/>



Expand Down Expand Up @@ -77,18 +69,25 @@ The Event entity returned by the `ModelManager` is represendted as an [ItemColle



## The BPMNModel

The Imixs `ModelManager` operates directly on BPMNModel instances from the [Open-BPMN Meta model](https://github.com/imixs/open-bpmn/tree/master/open-bpmn.metamodel).
The `BPMNModel` instance allows full access to a BPMN 2.0 model and provides a lot of convenient methods to navigate through a BPMN model.

Find further information at the [Open-BPMN Meta Project on Github](https://github.com/imixs/open-bpmn/tree/master/open-bpmn.metamodel).
## The ModelManager Interface
The `org.imixs.workflow.ModelManager` is used by the [WorkflowKernel](workflowkernel.html) to access model information during the processing life cycle. The ModelManager defines the following core methods:

## The OpenBPMNModelManager
|Method | Description |
|----------------------------|---------------------------|
|getModel(version) | Returns a BPMN Model by version. The method throws a ModelException in case the model version did not exits.|
|addModel(BPMNModel) | Adds a new Model to the ModelManager.|
|removeModel(version) | Removes a Model from the ModelManager.|
|loadDefinition(workitem) | Returns the BPMN Definition entity associated with a given workitem.|
|loadProcess(workitem) | Returns the BPMN Process entity associated with a given workitem. |
|loadTask(workitem) | Returns the BPMN Task entity associated with a given workitem.|
|loadEvent(workitem) | Returns the BPMN Event entity associated with a given workitem.|
|nextModelElement(event, workitem) | Returns the next BPMN Flow Entity followed by a given Event Entity.|

The `OpenBPMNModelManager` implements the interface `org.imixs.workflow.ModelManager` and can be used in any custom Java implementation of Imixs-Workflow. The `OpenBPMNModelManager` provides additional methods to manage BPMNModel instances and helper methods to navigate throug a BPMN model as also methods to evaluate specific model situations based on the [Imixs RuleEngine](ruleengine.md).

### BPMN Sequence Flows

The `ModelManager` provides methods to evaluate elements in a BPMN sequence flow based on the model definition. This includes also complex flows including any kind of gateway. The ModelManager evaluates conditional events on a Exclusive Gateway based on the [Imixs RuleEngine](ruleengine.md). This allows the creation of very complex BPMN 2.0 process models.

### The Imixs ModelService

Expand Down
2 changes: 1 addition & 1 deletion src/site/markdown/core/plugin-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ This concept makes it easy for a Plug-In Developer to implement additional busin
A Plug-In can validate a process instance and may also manipulate the business data. A Plug-In can also interrupt the processing phase by throwing a [PluginException](../engine/plugins/exception_handling.html) - for example in case of a validation error.


###The Two-Phase Commit
### The Two-Phase Commit
The Imixs Plugin-API defines three call-back methods, called by the WorkflowKernel for each Plug-In in one single transaction during the processing life-cycle. This is the concept of a two-phase commit (2PC).


Expand Down
6 changes: 3 additions & 3 deletions src/site/markdown/core/workflowkernel.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#The Workflow Kernel
# The Workflow Kernel

The class _org.imxis.workflow.WorkflowKernel_ is the core component of the Imixs-Workflow API. The _WorkflowKernel_ controls the processing life cycle of a process instance (Workitem) according to an Imixs-BPMN process model.
The class `org.imxis.workflow.WorkflowKernel` is the core component of the Imixs-Workflow API. The _WorkflowKernel_ controls the processing life cycle of a process instance (Workitem) according to an Imixs-BPMN process model.
The processing life cycle is defined by a BPMN _Event_ describing the transition between two BPMN _Task_ elements.

<img src="../images/modelling/example_01.png"/>
Expand Down Expand Up @@ -112,7 +112,7 @@ The WorkflowContext provides the following methods:
The session context is platform specific, for example a surrounding EJB Context, a Web Module or a Spring Context. As the _WorkflowKernel_ is part of the Imixs-Workflow core API it is a platform independent building block. Therefor the WorkflowContext builds a bridge between the Workflow System and the processing engine. For details about the concrete implementation see the [WorkflowService implementation](../engine/workflowservice.html).


##The Workflow Log
## The Workflow Log

The Imixs _WorkflowKernel_ generates a log entry during each processing phase with information about the current model version, the process entity and the processed workflow event. The log is stored in the property '$EventLog'.
The log entry has the following format:
Expand Down
21 changes: 16 additions & 5 deletions src/site/markdown/core/workflowmanager.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,17 @@
#The WorkflowManager
The WorkflowManager is the central interface for each implementation of an Imixs-Workflow Engine. This interface provides the general functionality to create, process and search Workitems.
The WorkflowManager instantiates the [WorkflowKernel](./workflowkernel.html) to process a WorkItem and provides the implementation of a Model. The WorkflowManager can be used by an application to process and search Workitems and provide the environment for the business logic implemented by the plugins.
# The WorkflowManager

The class `org.imixs.workflow.WorkflowManager` is the central interface for each implementation of an Imixs-Workflow Engine. This interface provides the general functionality to create, process and search Workitems.
The *WorkflowManager* instantiates the [WorkflowKernel](./workflowkernel.html) to process a WorkItem and provides the implementation of a Model. The WorkflowManager can be used by an application to process and search Workitems and provide the environment for the business logic implemented by the plugins.



|Method | Return Type |
|---------------------------|-------------------|
|processWorkItem(ItemCollection workitem)| Processes and persists a workItem. The WorkItem must provide at least the mandatory items *$modelVersion*, *$taskID*, and *$EventID* to identify the current state in a BPMN model. |
|getWorkItem(String id) | Returns a workItem by its uniqueID ($uniqueID) from the persistence layer |
|removeWorkItem(String id) | The method throws an AccessDeniedException if the work item cannot be removed due to its state or user permissions. |


The [WorkflowManager Service](../engine/workflowservice.html) implements the WorkflowManager based on the JEE architecture.

## The Plugin-API
Expand All @@ -18,7 +29,7 @@ The general workflow functions and also application specific business logic is p



##Processing a Workitem
## Processing a Workitem
The method 'processWorkItem()' is used to create or update a Workitem. The WorkflowManager implementation is responsible to load the Model, call the WorkflowKernel and persist the Workitem so it can be retrieved later by the application.

public void processWorkItem(ItemCollection aWorkItem)throws Exception {
Expand Down Expand Up @@ -48,7 +59,7 @@ The method returns a list of all workItems assigned to the current user. A work

wfm.removeWorkItem(workitem);

##The Imixs WorkflowService
## The Imixs WorkflowService

The Imixs-Workflow engine provides the WorkflowService component which implements the WorkflowManager on the JEE component stack. Find more information about the Imixs-WorkflowService in the section [WorkflowService](../engine/workflowservice.html).

4 changes: 2 additions & 2 deletions src/site/site.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,10 @@

<item name="Core API" href="core/index.html" collapse="true">
<item name="ItemCollection" href="core/itemcollection.html" />
<item name="Model" href="core/model.html" />
<item name="BPMN Model Manager" href="core/model.html" />
<item name="WorkflowKernel" href="core/workflowkernel.html" />
<item name="Plugins" href="core/plugin-api.html" />
<item name="Adapter" href="core/adapter-api.html" />
<item name="WorkflowKernel" href="core/workflowkernel.html" />
<item name="WorkflowManager" href="core/workflowmanager.html" />
<item name="XML" href="core/xml/index.html" collapse="true">
<item name="XML Adapter" href="core/xml/adapter.html" />
Expand Down

0 comments on commit 0760741

Please sign in to comment.