Skip to main content

BPMN Diagram

Introduction​

The BPMN diagram is the modeling area of a process. It is not part of the left hand side palette. However, it still has some overall process properties.

Properties​

General​

AttributeTypeDescriptionCategory
Model Key String

Model key of the process which serves as a unique ID to identify a model across different versions.

The model key is an important property, as the key is used in all kinds of API calls. When a BPMN process model is published to a runtime system a process definition is deployed. From that point on, new process instances can be started, often using the key when doing this programmatically or over REST. The key needs to be unique in a runtime system and therefor cannot be edited here.

The name is a user-readable name that is given to this BPMN process model. The documentation can be used to store free-form information about the BPMN process model.

Name Translatable to different languagesText

The name of the element. This is the name displayed in the diagram.

Documentation Multiline Text

A free-form text that can be used to explain details about the particular element.

Creation date ISO8601DateString

This defines the date on which the diagram was created.

These two timestamps indicate when the BPMN process model was created and when it got last updated.

Modification date ISO8601DateString

This defines the date on which the diagram was last modified.

Process Instance Name Expression usage possibleTranslatable to different languagesText

The name of the process instance. The Process sequence variable can be used in the expression

The Process Instance Name can be used to give the process instance a custom name. By default, the instance gets the name of the BPMN process model (Flowable Work) or nothing (Flowable Core). The name can be an expression that uses values from the start form.

The Process Instance Business Key is used to give the process instance a business key, which is typically some sort of business-specific identifier that can be used to easily find an instance.

The Category can be set to categorize published process definitions or filter definitions in queries.

Category Expression usage possibleText

Category (target namespace) of the process model. This allows you to group models according to your own criteria.

Assignment​

AttributeTypeDescriptionCategory
Assignee Expression usage possibleUser Selection

User ID of the task's assignee. The assignee can see and complete a task and is usually the person responsible for it.

The assignee and owner of a process instance typically have broad set of rights to view and edit information. Using a security policy in the security tab on this BPMN process model, this can be changed.

Once an assignee or owner is set, a flag appears that can be used to disable the automatic propagation of the initiator of the process instance as an assignee and owner. This is only applicable for root instances, as child instances inherit these roles differently.

Owner Expression usage possibleUser Selection

The ID of the task's owner.

Potential starter user Expression usage possibleUser Selection

A user that can start the process.

The Potential starter users or groups determine which users or groups can start process instances from a published definition of this BPMN process model.

In Flowable Work, this is automatic. In Flowable Core, this information is available as metadata to build your own filters.

Potential starter group Expression usage possibleGroup Selection

A group that can start the process.

Details​

AttributeTypeDescriptionCategory
Author Text

Author of the process definition.

The Author and Version are metadata fields, they have no impact on runtime execution.

The Is executable flag can be unchecked to indicate this is a model for documentation purposes and not to be executed.

Version Text

This defines the version number of the diagram.

Is executable Boolean

An optional boolean value specifying whether the process is executable.

Signal definitions List

Contains the definition of all signals of this process which can then be referenced in Signal Events. A signal can be global or local, depending on whether throwing it will affect all processes or be limited to the parent process instance.

Signal events in BPMN are used as an implementation of the observer pattern: signal events can be thrown from anywhere and any process instance can be listening on them. Signal events are defined on the BPMN model level and referenced in for example the boundary signal event, the signal throw event, etc.

By default signals are global (across process instances), but they can be limited to intra-process-instance communication only too.

Message definitions List

Contains the definitions of all messages of this process which can be referenced in Message Events.

Message events in BPMN are used as a way to communicate between different parts of a model. Message events are defined on the BPMN model level and referenced in for example the boundary message event, the message throw event, etc.

Audit​

AttributeTypeDescriptionCategory
History level Selection:
  • Default
  • None
  • Instance
  • Task
  • Activity
  • Audit
  • Full

Set a specific history level for this process definition.

None: Skips all history archiving. This is the most performant for runtime process execution, but no historical information will be available.

Activity: Archives all process instances and activity instances. At the end of the process instance, the latest values of the top level process instance variables will be copied to historic variable instances. No details will be archived.

Audit: Archives all process instances, activity instances, keeps variable values continuously in sync and all form properties that are submitted so that all user interaction through forms is traceable and can be audited.

Full: Highest level of history archiving and hence the slowest. This level stores all information as in the audit level plus all other possible details, mostly these are process variable updates.

The History Level is a setting that determines how much historical data is kept for a process instance of this BPMN process model. Flowable uses audit level by default, which gives a good balance between performance and storing enough historical data. in certain situations such as for example high-volume microservice orchestrations there is no need to store all this data or any data at all. In such situations, it might be worthwhile to use a history level that stores less data as to let the data store size not grow out of control.

See the documentation for more details on each of the levels.

Advanced​

Advanced options​

AttributeTypeDescriptionCategory
Data objects List

Defines the Data Objects of the process or Sub-Process. Each data object will be initialized as a process variable under the defined name.

With data objects, process instance variables can be initialized when process instance is started.

Note: these data objects are part of the BPMN specification and are not to be confused with the data object models in Flowable.

Eager fetching Boolean

Enable eager execution fetching for this process definition. If true, whenever an execution is fetched from the data store, the whole execution tree is fetched in the same round trip. The property "enableEagerExecutionTreeFetching" must be set to true in your global PerformanceSettings to use this feature.

This is an advanced experimental setting: if checked, all data related to a process instance will be fetched eagerly in one database roundtrip, versus fetching what is needed when the runtime execution needs it. This might speed up certain use cases, where the dataset is small.

Event listeners List

Listeners for any event happening in the Flowable Engine. It is also possible to rethrow the event as a signal, message or error event.

ACTIVITY_COMPENSATE: An activity is about to be compensated.

* ACTIVITY_COMPLETED: An activity is completed successfully

* ACTIVITY_ERROR_RECEIVED: An activity has received an error event.

* ACTIVITY_MESSAGE_RECEIVED: An activity received a message.

* ACTIVITY_SIGNALED: An activity received a signal

* ACTIVITY_STARTED: An activity is starting to execute

* ENGINE_CLOSED: The process-engine this listener is attached to has been closed.

* ENGINE_CREATED: The process-engine this listener is attached to has been created and is ready for API-calls.

* ENTITY_ACTIVATED: An existing entity is activated.

* ENTITY_CREATED: A new entity is created.

* ENTITY_DELETED: An existing entity is deleted.

* ENTITY_INITIALIZED: A new entity has been created and is fully initialized.

* ENTITY_SUSPENDED: An existing entity is suspended.

* ENTITY_UPDATED: An existing entity is updated.

* JOB_EXECUTION_FAILURE: The execution of a job has failed.

* JOB_EXECUTION_SUCCESS: A job has been executed successfully.

* JOB_RETRIES_DECREMENTED: The number of job retries have been decremented due to a failed job.

* MEMBERSHIP_CREATED: A user has been added to a group.

* MEMBERSHIP_DELETED: A user has been removed from a group.

* MEMBERSHIPS_DELETED: All members will be removed from a group.

* TASK_ASSIGNED: A task has been assigned to a user.

* TASK_COMPLETED: A task has been completed.

* TIMER_FIRED: A timer has been fired.

* UNCAUGHT_BPMN_ERROR: An uncaught BPMN Error has been thrown.

* VARIABLE_CREATED: A variable has been created.

* VARIABLE_DELETED: An existing variable has been deleted.

* VARIABLE_UPDATED: An existing variable has been updated.

With an event listener it's possible attach custom logic to low-level runtime events that are fired during process instance execution.

Listeners​

AttributeTypeDescriptionCategory
Execution listeners List

Allows invoking custom after certain lifecycle events.

Start: Executes after the activity has been started.

End: Executes after the activity was completed.

Transition: When defined on a sequence flow, executes once the flow is transition is taken.

Execution listeners are used to add logic on certain lifecycle events, in this case process instance start and completion.

Typically it is used to add extra technical logic which shouldn't be visible in the BPMN process model.

List Attribute Details​

Signal definitions​

AttributeTypeDescription
Model Id Text

A unique id for the signal event.

Name Text

A user-readable name for the signal event.

Scope RequiredSelection:
  • Global
  • Process Instance

Whether all process instances can listener for this signal event, or only listeners within the same process instance.

Message definitions​

AttributeTypeDescription
Model Id Text

A unique id for the message event.

Name Text

A user-readable name for the message event.

Data objects​

AttributeTypeDescription
ID of the data object Text

Provide a unique identifier for this entry.

Name Text

Provide a human-readable name for this entry.

Type RequiredSelection:
  • String
  • Long
  • Boolean
  • Date
  • Enum

Select one of the supported types for this entry.

Default value Text

Provide a value for this entry.

Event listeners​

AttributeTypeDescription
Event RequiredSelection:
  • ACTIVITY_COMPENSATE
  • ACTIVITY_COMPLETED
  • ACTIVITY_ERROR_RECEIVED
  • ACTIVITY_MESSAGE_RECEIVED
  • ACTIVITY_SIGNALED
  • ACTIVITY_STARTED
  • ENGINE_CLOSED
  • ENGINE_CREATED
  • ENTITY_ACTIVATED
  • ENTITY_CREATED
  • ENTITY_DELETED
  • ENTITY_INITIALIZED
  • ENTITY_SUSPENDED
  • ENTITY_UPDATED
  • JOB_EXECUTION_FAILURE
  • JOB_EXECUTION_SUCCESS
  • JOB_RETRIES_DECREMENTED
  • MEMBERSHIP_CREATED
  • MEMBERSHIP_DELETED
  • MEMBERSHIPS_DELETED
  • TASK_ASSIGNED
  • TASK_COMPLETED
  • TIMER_FIRED
  • UNCAUGHT_BPMN_ERROR
  • VARIABLE_CREATED
  • VARIABLE_DELETED
  • VARIABLE_UPDATED

The type of event that the listener should listen to.

Class Text

Fully qualified classname of a class to be invoked when executing the task. The class must implement either JavaDelegate or ActivityBehavior.

Delegate expression Text

Delegate Expression to be executed when the task is started. A delegate expression must resolve to a Java object, for instance a Spring bean. The object's class must implement either JavaDelegate or ActivityBehavior.

Entity type Text

Type of entity that should be targeted by events for which the event-listener should be notified, which allows to filter the events that are received by this listener.

Rethrow event? Boolean
Rethrow event type Selection:
  • error
  • message
  • signal
  • globalSignal

If set, an event that is received will be rethrown. Use 'error', 'message', 'signal' or 'globalSignal' to define the type.

Rethrow event name Text

If the Rethrow event type is set, this defines the name under which the error, message or signal is thrown.

Execution listeners​

AttributeTypeDescription
Event RequiredSelection:
  • Start
  • End
  • Take

The lifecycle event. The 'Take' event is only available for sequence flow.

Class Text

Fully qualified classname of a class to be invoked when executing the task. The class must implement either JavaDelegate or ActivityBehavior.

Expression Text

JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.

Delegate expression Text

Delegate Expression to be executed when the task is started. A delegate expression must resolve to a Java object, for instance a Spring bean. The object's class must implement either JavaDelegate or ActivityBehavior.

Fields List

Fields​

AttributeTypeDescription
Name Text

The name of the element. This is the name displayed in the diagram.

String value Text
Expression Text

JUEL Expression to be executed when the task is started. Expressions allow you to interact with the backend by calling services, making calculations etc. You can find more information about expressions in the documentation.

String Text