diff --git a/content/reference/bpmn20/custom-extensions/extension-attributes.md b/content/reference/bpmn20/custom-extensions/extension-attributes.md index 379b09b08..804ab2827 100644 --- a/content/reference/bpmn20/custom-extensions/extension-attributes.md +++ b/content/reference/bpmn20/custom-extensions/extension-attributes.md @@ -1302,7 +1302,7 @@ The following attributes are extension attributes for the `camunda` namespace `h Description - The attribute specifies the history time to live (in days) for the process definition. It is used within }}">History cleanup. + The attribute specifies the history time to live (in days) for the process definition. It is used within }}">History cleanup. diff --git a/content/reference/cmmn11/custom-extensions/camunda-attributes.md b/content/reference/cmmn11/custom-extensions/camunda-attributes.md index b5eaab15b..ce1e601fa 100644 --- a/content/reference/cmmn11/custom-extensions/camunda-attributes.md +++ b/content/reference/cmmn11/custom-extensions/camunda-attributes.md @@ -471,7 +471,7 @@ The following attributes are extension attributes for the `camunda` namespace `h Description - The attribute specifies the history time to live (in days) for the case definition. It is used within }}">History cleanup. + The attribute specifies the history time to live (in days) for the case definition. It is used within }}">History cleanup. diff --git a/content/reference/deployment-descriptors/tags/process-engine.md b/content/reference/deployment-descriptors/tags/process-engine.md index 47300d587..873e0af8e 100644 --- a/content/reference/deployment-descriptors/tags/process-engine.md +++ b/content/reference/deployment-descriptors/tags/process-engine.md @@ -471,7 +471,7 @@ The following is a list with the most commonly used process engine configuration history String - Sets the }}">level of the process engine history. + Sets the }}">level of the process engine history.

Values: none, activity, audit, full.

@@ -497,7 +497,7 @@ The following is a list with the most commonly used process engine configuration historyRemovalTimeStrategy String - Controls if and when the }}">removal time of an historic instance is set. + Controls if and when the }}">removal time of an historic instance is set. The default value is end.
Please also see the }}">historyCleanupStrategy configuration parameter.

@@ -1115,7 +1115,7 @@ The following is a list with the most commonly used process engine configuration historyCleanupStrategy String - Controls which }}">History cleanup strategy is used. + Controls which }}">History cleanup strategy is used. The default value is removalTimeBased.
Please also see the }}">historyRemovalTimeStrategy configuration parameter.

Values: removalTimeBased, endTimeBased. @@ -1129,27 +1129,27 @@ The following is a list with the most commonly used process engine configuration historyCleanupBatchWindowStartTime String - }}">History cleanup batch window start time in the format HH:mmZ (Z is for RFC 822 time zone) or HH:mm. E.g., 20:00+0100 or 20:00. In case of null, no batch window is considered to be configured + }}">History cleanup batch window start time in the format HH:mmZ (Z is for RFC 822 time zone) or HH:mm. E.g., 20:00+0100 or 20:00. In case of null, no batch window is considered to be configured and history cleanup can only be called manually. historyCleanupBatchWindowEndTime String - }}">History cleanup batch window end time in the format HH:mmZ (Z is for RFC 822 time zone) or HH:mm. E.g., 23:00-0300 or 23:00. In case batchWindowEndTime exceeds batchWindowStartTime it is considered + }}">History cleanup batch window end time in the format HH:mmZ (Z is for RFC 822 time zone) or HH:mm. E.g., 23:00-0300 or 23:00. In case batchWindowEndTime exceeds batchWindowStartTime it is considered to be on the same date (e.g., cleanup runs each day between 20:00 and 23:00). Otherwise it is considered to be on the next calendar day (e.g., cleanup starts each day at 20:00 and finishes the next day at 01:00). Default value is `00:00`. mondayHistoryCleanupBatchWindowStartTime String - }}">History cleanup batch window start time for Mondays. Requires the same format as historyCleanupBatchWindowStartTime. + }}">History cleanup batch window start time for Mondays. Requires the same format as historyCleanupBatchWindowStartTime. In case it is not configured, batch window configured with historyCleanupBatchWindowStartTime and historyCleanupBatchWindowEndTime will be used for this day of week. mondayHistoryCleanupBatchWindowEndTime String - }}">History cleanup batch window end time for Mondays. Requires the same format and follows the same logic + }}">History cleanup batch window end time for Mondays. Requires the same format and follows the same logic as historyCleanupBatchWindowEndTime. @@ -1254,7 +1254,7 @@ The following is a list with the most commonly used process engine configuration Boolean Configures whether the engine participates in history cleanup or not. The default value is true. - For more details, please see }}">Cleanup Execution Participation per Node + For more details, please see }}">Cleanup Execution Participation per Node in the User Guide. diff --git a/content/reference/dmn/custom-extensions/camunda-attributes.md b/content/reference/dmn/custom-extensions/camunda-attributes.md index 4898fac58..92f638e98 100644 --- a/content/reference/dmn/custom-extensions/camunda-attributes.md +++ b/content/reference/dmn/custom-extensions/camunda-attributes.md @@ -20,7 +20,7 @@ The following attributes are extension attributes for the `camunda` namespace `h Description - The attribute specifies the history time to live (in days) for the decision definition. It is used within }}">History cleanup. + The attribute specifies the history time to live (in days) for the decision definition. It is used within }}">History cleanup. diff --git a/content/update/minor/710-to-711/_index.md b/content/update/minor/710-to-711/_index.md index 5dad76fc5..b0cbdc277 100644 --- a/content/update/minor/710-to-711/_index.md +++ b/content/update/minor/710-to-711/_index.md @@ -231,7 +231,7 @@ In order to read (or delete) entries that are not related to process definitions * permission `READ` (or `DELETE`) on resource `UserOperationLogCategory` with the resource id set to the respective category of the entry or `*` -An overview of the operation logs and their categories can be found at [User Operation Log]({{< ref "/user-guide/process-engine/history.md#glossary-of-operations-logged-in-the-user-operation-log" >}}). +An overview of the operation logs and their categories can be found at [User Operation Log]({{< ref "/user-guide/process-engine/history/user-operation-log.md#glossary-of-operations-logged-in-the-user-operation-log" >}}). Authorization management is detailed in [Authorization Service]({{< ref "/user-guide/process-engine/authorization-service.md" >}}). # Custom WritableIdentityProvider diff --git a/content/update/minor/714-to-715/_index.md b/content/update/minor/714-to-715/_index.md index 7f1e47d06..d2df92118 100644 --- a/content/update/minor/714-to-715/_index.md +++ b/content/update/minor/714-to-715/_index.md @@ -194,7 +194,7 @@ You can read more about the metrics in our [Metrics Guide]({{< ref "/user-guide/ Since the metrics data accumulated over time can become substantial, it is possible to -* configure a history time live for the task metrics data so it is picked up by [History Cleanup]({{< ref "/user-guide/process-engine/history.md#task-metrics" >}}) +* configure a history time live for the task metrics data so it is picked up by [History Cleanup]({{< ref "/user-guide/process-engine/history/history-configuration.md#task-metrics" >}}) * manually clean up the task metrics data through API Manually deleting task metrics data can be done via {{< restref page="deleteTaskMetrics" text="REST API" tag="Metrics" >}} or Java API by using the `deleteTaskMetrics` method provided by the `ManagementService`. diff --git a/content/update/minor/719-to-720/_index.md b/content/update/minor/719-to-720/_index.md index bb9247e6f..aa7faf574 100644 --- a/content/update/minor/719-to-720/_index.md +++ b/content/update/minor/719-to-720/_index.md @@ -85,7 +85,7 @@ their historic data grow over time and remain uncleaned due to this configuratio we decided to make the historyTimeToLive mandatory for new deployments or redeployments. At the same time, we acknowledge there might be use cases (e.g. when there are no history events fired at all, -see [history level]({{< ref "/user-guide/process-engine/history.md#set-the-history-level" >}}) configuration) +see [history level]({{< ref "/user-guide/process-engine/history/history-configuration.md#set-the-history-level" >}}) configuration) where our users might favour to keep the legacy behaviour despite our recommendation. If that is the case, you can always turn off the feature by setting the feature flag `enforceHistoryTimeToLive` to `false`. For more information, checkout the new parameter description under }}">Configuration Properties. diff --git a/content/update/minor/73-to-74/_index.md b/content/update/minor/73-to-74/_index.md index 1dd330902..13258e478 100644 --- a/content/update/minor/73-to-74/_index.md +++ b/content/update/minor/73-to-74/_index.md @@ -125,7 +125,7 @@ This is already the default for Camunda 7 versions after and including 7.3.3 and ### User Operation Log -The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. +The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. Furthermore, with 7.4 task events are only logged when they occur in the context of a logged in user. Task events are accessible via the deprecated API `TaskService#getTaskEvents`. If you rely on this API method, the previous behavior can be restored by setting the flag `restrictUserOperationLogToAuthenticatedUsers` to `false`. diff --git a/content/update/minor/73-to-74/glassfish.md b/content/update/minor/73-to-74/glassfish.md index c6734338e..6af22849c 100644 --- a/content/update/minor/73-to-74/glassfish.md +++ b/content/update/minor/73-to-74/glassfish.md @@ -95,7 +95,7 @@ This is already the default for Camunda 7 versions after and including 7.3.3 and ## User Operation Log -The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. +The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. Furthermore, with 7.4 task events are only logged when they occur in the context of a logged in user. Task events are accessible via the deprecated API `TaskService#getTaskEvents`. If you rely on this API method, the previous behavior can be restored by setting the flag `restrictUserOperationLogToAuthenticatedUsers` to `false`. diff --git a/content/update/minor/73-to-74/jboss.md b/content/update/minor/73-to-74/jboss.md index 889a0cdb0..e576fd15a 100644 --- a/content/update/minor/73-to-74/jboss.md +++ b/content/update/minor/73-to-74/jboss.md @@ -105,7 +105,7 @@ This is already the default for Camunda 7 versions after and including 7.3.3 and ## User Operation Log -The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. +The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. Furthermore, with 7.4 task events are only logged when they occur in the context of a logged in user. Task events are accessible via the deprecated API `TaskService#getTaskEvents`. If you rely on this API method, the previous behavior can be restored by setting the flag `restrictUserOperationLogToAuthenticatedUsers` to `false`. diff --git a/content/update/minor/73-to-74/tomcat.md b/content/update/minor/73-to-74/tomcat.md index 2f4b4793e..e3c21f5cc 100644 --- a/content/update/minor/73-to-74/tomcat.md +++ b/content/update/minor/73-to-74/tomcat.md @@ -102,7 +102,7 @@ This is already the default for Camunda 7 versions after and including 7.3.3 and ## User Operation Log -The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. +The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. Furthermore, with 7.4 task events are only logged when they occur in the context of a logged in user. Task events are accessible via the deprecated API `TaskService#getTaskEvents`. If you rely on this API method, the previous behavior can be restored by setting the flag `restrictUserOperationLogToAuthenticatedUsers` to `false`. diff --git a/content/update/minor/73-to-74/was.md b/content/update/minor/73-to-74/was.md index 373a1ceda..99ac087ff 100644 --- a/content/update/minor/73-to-74/was.md +++ b/content/update/minor/73-to-74/was.md @@ -97,7 +97,7 @@ This is already the default for Camunda 7 versions after and including 7.3.3 and ## User Operation Log -The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. +The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. Furthermore, with 7.4 task events are only logged when they occur in the context of a logged in user. Task events are accessible via the deprecated API `TaskService#getTaskEvents`. If you rely on this API method, the previous behavior can be restored by setting the flag `restrictUserOperationLogToAuthenticatedUsers` to `false`. diff --git a/content/update/minor/73-to-74/wls.md b/content/update/minor/73-to-74/wls.md index 42004abe8..a06a8e078 100644 --- a/content/update/minor/73-to-74/wls.md +++ b/content/update/minor/73-to-74/wls.md @@ -87,7 +87,7 @@ This is already the default for Camunda 7 versions after and including 7.3.3 and ## User Operation Log -The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. +The behavior of the [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) has changed, so that operations are only logged if they are performed in the context of a logged in user. This behavior can be toggled in the process engine configuration using the property `restrictUserOperationLogToAuthenticatedUsers` (default `true`). To restore the engine's prior behavior, i.e., to write log entries regardless of user context, set the flag to `false`. Furthermore, with 7.4 task events are only logged when they occur in the context of a logged in user. Task events are accessible via the deprecated API `TaskService#getTaskEvents`. If you rely on this API method, the previous behavior can be restored by setting the flag `restrictUserOperationLogToAuthenticatedUsers` to `false`. diff --git a/content/update/minor/76-to-77/_index.md b/content/update/minor/76-to-77/_index.md index 408d24104..8d712ff11 100644 --- a/content/update/minor/76-to-77/_index.md +++ b/content/update/minor/76-to-77/_index.md @@ -30,7 +30,7 @@ Noteworthy new Features and Changes in 7.7: * [Deploy Processes, Decisions and Cases from Cockpit]({{< ref "/webapps/cockpit/deployment-view.md#create-deployment" >}}) * [New Batch API for modification of multiple process instances]({{< ref "/user-guide/process-engine/process-instance-modification.md#modification-of-multiple-process-instances" >}}) * [Process instance restart + Batch API]({{< ref "/user-guide/process-engine/process-instance-restart.md" >}}) -* [Automatic cleanup of historic data based on TTL]({{< ref "/user-guide/process-engine/history.md#history-cleanup" >}}) +* [Automatic cleanup of historic data based on TTL]({{< ref "/user-guide/process-engine/history/history-cleanup.md" >}}) * [New cryptographic hash function with salt] ({{< ref "/user-guide/process-engine/password-hashing.md" >}}) * {{< restref text="External tasks history" tag="Historic-External-Task-Log" >}} diff --git a/content/update/minor/79-to-710/_index.md b/content/update/minor/79-to-710/_index.md index e64961a5b..bb06b4742 100644 --- a/content/update/minor/79-to-710/_index.md +++ b/content/update/minor/79-to-710/_index.md @@ -168,9 +168,9 @@ to preserve the previous behavior. ## Changed Default Cleanup Strategy -The default strategy of the [History Cleanup]({{< ref "/user-guide/process-engine/history.md#history-cleanup">}}) feature +The default strategy of the [History Cleanup]({{< ref "/user-guide/process-engine/history/history-cleanup.md">}}) feature has been changed. From now on, each historic instance related to processes, decisions or batches needs a -[removal time]({{< ref "/user-guide/process-engine/history.md#removal-time">}}) to be cleaned-up. +[removal time]({{< ref "/user-guide/process-engine/history/history-configuration.md#removal-time">}}) to be cleaned-up. Historic instances which (1) have been produced by a Camunda 7 version prior to 7.10 and (2) belong to a top-level instance which has been completed already cannot be cleaned-up after the migration took place. This is due to the reason, that a @@ -186,12 +186,12 @@ You can learn more about it in the [User Guide]({{< ref "/user-guide/process-eng {{< /note >}} To gain a better understanding of the new cleanup strategy, please see the updated documentation about the -[History Cleanup]({{< ref "/user-guide/process-engine/history.md#history-cleanup">}}) feature. +[History Cleanup]({{< ref "/user-guide/process-engine/history/history-cleanup.md">}}) feature. ### Custom History Level -If you have implemented a [Custom History Level]({{< ref "/user-guide/process-engine/history.md#implement-a-custom-history-level">}}) +If you have implemented a [Custom History Level]({{< ref "/user-guide/process-engine/history/custom-implementation.md#implement-a-custom-history-level">}}) and you want to use it in conjunction with the removal time based cleanup strategy, please also see the documentation about -[Removal Time Inheritance]({{< ref "/user-guide/process-engine/history.md#removal-time-inheritance">}}). +[Removal Time Inheritance]({{< ref "/user-guide/process-engine/history/history-configuration.md#removal-time-inheritance">}}). # Changed Webjar Structure diff --git a/content/user-guide/process-engine/authorization-service.md b/content/user-guide/process-engine/authorization-service.md index a044dc772..ce2c5188f 100644 --- a/content/user-guide/process-engine/authorization-service.md +++ b/content/user-guide/process-engine/authorization-service.md @@ -1038,4 +1038,4 @@ On these databases, revoke authorizations are effectively unusable. Also see the [Configuration Options](#check-revoke-authorizations) section on this page. [hist-inst-perm-config-flag]: {{< ref "/reference/deployment-descriptors/tags/process-engine.md#enable-historic-instance-permissions" >}} -[Removal-Time-based History Cleanup Strategy]: {{< ref "/user-guide/process-engine/history.md#removal-time-based-strategy" >}} +[Removal-Time-based History Cleanup Strategy]: {{< ref "/user-guide/process-engine/history/history-cleanup.md#removal-time-based-strategy" >}} diff --git a/content/user-guide/process-engine/batch.md b/content/user-guide/process-engine/batch.md index 285dd4646..0779fe10d 100644 --- a/content/user-guide/process-engine/batch.md +++ b/content/user-guide/process-engine/batch.md @@ -324,8 +324,8 @@ You can configure the property in three ways: [seed job]: #seed-job [retry]: {{< ref "/user-guide/process-engine/the-job-executor.md#failed-jobs" >}} [incidents]: {{< ref "/user-guide/process-engine/incidents.md" >}} -[history level]: {{< ref "/user-guide/process-engine/history.md#choose-a-history-level" >}} -[history cleanup]: {{< ref "/user-guide/process-engine/history.md#history-time-to-live-for-batch-operations" >}} +[history level]: {{< ref "/user-guide/process-engine/history/history-configuration.md#choose-a-history-level" >}} +[history cleanup]: {{< ref "/user-guide/process-engine/history/history-cleanup.md#history-time-to-live-for-batch-operations" >}} [job prioritization]: {{< ref "/user-guide/process-engine/the-job-executor.md#job-prioritization" >}} [job-definition-priority]: {{< ref "/user-guide/process-engine/the-job-executor.md#override-priority-by-job-definition" >}} [job-priority]: {{< ref "/user-guide/process-engine/the-job-executor.md#set-job-priorities-via-managementservice-api" >}} diff --git a/content/user-guide/process-engine/database/cockroachdb-configuration.md b/content/user-guide/process-engine/database/cockroachdb-configuration.md index 18d15d998..1bc315593 100644 --- a/content/user-guide/process-engine/database/cockroachdb-configuration.md +++ b/content/user-guide/process-engine/database/cockroachdb-configuration.md @@ -93,7 +93,7 @@ recommendations on how to configure and use the process engine with CockroachDB. ### Un-ignorable historic `OptimisticLockingException` The process engine may generate large amounts of historical data, and provides the [history cleanup -feature]({{< ref "/user-guide/process-engine/history.md#history-cleanup" >}}) to ensure that "old" +feature]({{< ref "/user-guide/process-engine/history/history-cleanup.md" >}}) to ensure that "old" data is removed. The History Cleanup Removal-Time-based Strategy allows for historical data associated with still running Process Instances to be cleaned up. Since running Process Instances continue generating historical data, removing the same data in parallel is viewed as an `OptimisticLockingException`. diff --git a/content/user-guide/process-engine/decisions/_index.md b/content/user-guide/process-engine/decisions/_index.md index 84039545c..4cc15fe13 100644 --- a/content/user-guide/process-engine/decisions/_index.md +++ b/content/user-guide/process-engine/decisions/_index.md @@ -20,4 +20,4 @@ cases. Evaluated decisions are saved in the [History] for auditing and reporting [Camunda DMN engine]: {{< ref "/user-guide/dmn-engine/_index.md" >}} [Services API]: {{< ref "/user-guide/process-engine/process-engine-api.md#services-api" >}} -[History]: {{< ref "/user-guide/process-engine/history.md" >}} +[History]: {{< ref "/user-guide/process-engine/history/history-configuration.md" >}} diff --git a/content/user-guide/process-engine/decisions/history.md b/content/user-guide/process-engine/decisions/history.md index fa74304c7..ae3dd9f39 100644 --- a/content/user-guide/process-engine/decisions/history.md +++ b/content/user-guide/process-engine/decisions/history.md @@ -215,7 +215,7 @@ You can audit the evaluated decision definitions in the [Cockpit] webapp. [Cockpit]: {{< ref "/webapps/cockpit/dmn/_index.md" >}} -[History and Audit Event Log]: {{< ref "/user-guide/process-engine/history.md" >}} +[History and Audit Event Log]: {{< ref "/user-guide/process-engine/history/history-configuration.md" >}} [DMN 1.3 reference]: {{< ref "/reference/dmn/decision-table/hit-policy.md" >}} [BPMN business rule task]: {{< ref "/reference/bpmn20/tasks/business-rule-task.md#using-camunda-dmn-engine" >}} [CMMN decision task]: {{< ref "/reference/cmmn11/tasks/decision-task.md" >}} diff --git a/content/user-guide/process-engine/history.md b/content/user-guide/process-engine/history.md deleted file mode 100644 index fd8434725..000000000 --- a/content/user-guide/process-engine/history.md +++ /dev/null @@ -1,1962 +0,0 @@ ---- - -title: 'History and Audit Event Log' -weight: 140 - -menu: - main: - identifier: "user-guide-process-engine-history" - parent: "user-guide-process-engine" - ---- - - -The History Event Stream provides audit information about executed process instances. - -{{< img src="../img/process-engine-history.png" title="Process Engine History" >}} - -The process engine maintains the state of running process instances inside the database. This includes *writing* (1.) the state of a process instance to the database as it reaches a wait state and *reading* (2.) the state as process execution continues. We call this database the *runtime database*. In addition to maintaining the runtime state, the process engine creates an audit log providing audit information about executed process instances. We call this event stream the *history event stream* (3.). The individual events which make up this event stream are called *History Events* and contain data about executed process instances, activity instances, changed process variables and so forth. In the default configuration, the process engine will simply write (4.) this event stream to the *history database*. The `HistoryService` API allows querying this database (5.). The history database and the history service are optional components; if the history event stream is not logged to the history database or if the user chooses to log events to a different database, the process engine is still able to work and it is still able to populate the history event stream. This is possible because the BPMN 2.0 Core Engine component does not read state from the history database. It is also possible to configure the amount of data logged, using the `historyLevel` setting in the process engine configuration. - -Since the process engine does not rely on the presence of the history database for generating the history event stream, it is possible to provide different backends for storing the history event stream. The default backend is the `DbHistoryEventHandler` which logs the event stream to the history database. It is possible to exchange the backend and provide a custom storage mechanism for the history event log. - - -# Choose a History Level - -The history level controls the amount of data the process engine provides via the history event stream. The following settings are available out of the box: - -* `NONE`: no history events are fired. -* `ACTIVITY`: the following events are fired: - * Process Instance START, UPDATE, END, MIGRATE: fired as process instances are being started, updated, ended and migrated - * Case Instance CREATE, UPDATE, CLOSE: fired as case instances are being created, updated and closed - * Activity Instance START, UPDATE, END, MIGRATE: fired as activity instances are being started, updated, ended and migrated - * Case Activity Instance CREATE, UPDATE, END: fired as case activity instances are being created, updated and ended - * Task Instance CREATE, UPDATE, COMPLETE, DELETE, MIGRATE: fired as task instances are being created, updated (i.e., re-assigned, delegated etc.), completed, deleted and migrated. -* `AUDIT`: in addition to the events provided by history level `ACTIVITY`, the following events are fired: - * Variable Instance CREATE, UPDATE, DELETE, MIGRATE: fired as process variables are created, updated, deleted and migrated. The default history backend (DbHistoryEventHandler) writes variable instance events to the historic variable instance database table. Rows in this table are updated as variable instances are updated, meaning that only the last value of a process variable will be available. -* `FULL`: in addition to the events provided by history level `AUDIT`, the following events are fired: - * Form property UPDATE: fired as form properties are being created and/or updated. - * The default history backend (DbHistoryEventHandler) writes historic variable updates to the database. This makes it possible to inspect the intermediate values of a process variable using the history service. - * User Operation Log UPDATE: fired when a user performs an operation like claiming a user task, delegating a user task etc. - * Incidents CREATE, DELETE, RESOLVE, MIGRATE: fired as incidents are being created, deleted, resolved and migrated - * Historic Job Log CREATE, FAILED, SUCCESSFUL, DELETED: fired as a job is being created, a job execution failed or was successful or a job was deleted - * Decision Instance EVALUATE: fired when a decision is evaluated by the DMN engine. - * Batch START, END: fired as batches are being started and ended - * Identity links ADD, DELETE: fired when an identity link is being added, deleted or when an assignee of a user task is set or changed and when the owner of a user task is set or changed. - * Historic External Task Log CREATED, DELETED, FAILED, SUCCESSFUL: fired as an external task has been created, deleted or an external task execution has been reported to fail or succeed. -* `AUTO`: The level `auto` is useful if you are planning to run multiple engines on the same database. In that case, all engines have to use the same history level. Instead of manually keeping your configurations in sync, use the level `auto` and the engine determines the level already configured in the database automatically. If none is found, the default value `audit` is used. Keep in mind: If you are planning to use custom history levels, you have to register the custom levels for every configuration, otherwise an exception is thrown. - -If you need to customize the amount of history events logged, you can provide a custom implementation {{< javadocref page="org/camunda/bpm/engine/impl/history/producer/HistoryEventProducer.html" text="HistoryEventProducer" >}} and wire it in the process engine configuration. - - -# Set the History Level - -The history level can be provided as a property in the process engine configuration. Depending on how the process engine is configured, the property can be set using Java code: - -```java -ProcessEngine processEngine = ProcessEngineConfiguration - .createProcessEngineConfigurationFromResourceDefault() - .setHistory(ProcessEngineConfiguration.HISTORY_FULL) - .buildProcessEngine(); -``` - -It can also be set using Spring XML or a deployment descriptor (bpm-platform.xml, processes.xml). When using the Camunda Wildfly Subsystem, the property can be set through Wildfly configuration (standalone.xml, domain.xml). - -```xml -audit -``` - -Note that when using the default history backend, the history level is stored in the database and cannot be changed later. - -{{< note title="History levels and Cockpit" class="info" >}} -[Camunda Cockpit]({{< ref "/webapps/cockpit/_index.md" >}}) web application works best with History Level set to `FULL`. "Lower" History Levels will disable certain history-related features. -{{< /note >}} - -# The Default History Implementation - -The default history database writes History Events to the appropriate database tables. The database tables can then be queried using the `HistoryService` or using the REST API. - - -## History Entities - -There are the following History entities, which - in contrast to the runtime data - will also remain present in the DB after process and case instances have been completed: - -* `HistoricProcessInstances` containing information about current and past process instances. -* `HistoricVariableInstances` containing information about the latest state a variable held in a process instance. -* `HistoricCaseInstances` containing information about current and past case instances. -* `HistoricActivityInstances` containing information about a single execution of an activity. -* `HistoricCaseActivityInstances` containing information about a single execution of a case activity. -* `HistoricTaskInstances` containing information about current and past (completed and deleted) task instances. -* `HistoricDetails` containing various kinds of information related to either a historic process instances, an activity instance or a task instance. -* `HistoricIncidents` containing information about current and past (i.e., deleted or resolved) incidents. -* `UserOperationLogEntry` log entry containing information about an operation performed by a user. This is used for logging actions such as creating a new task, completing a task, etc. -* `HistoricJobLog` containing information about the job execution. The log provides details about the lifecycle of a job. -* `HistoricDecisionInstance` containing information about a single evaluation of a decision, including the input and output values. -* `HistoricBatch` containing information about current and past batches. -* `HistoricIdentityLinkLog` containing information about current and past (added, deleted, assignee is set or changed and owner is set or changed) identity links. -* `HistoricExternalTaskLog` containing information about the external log. The log provides details about the lifecycle of an external task. - - -## State of HistoricProcessInstances - -For every process instance process engine will create single record in history database and will keep updating this record during process execution. Every HistoricProcessInstance record can get one of the following states assigned: - -* ACTIVE - running process instance -* SUSPENDED - suspended process instances -* COMPLETED - completed through normal end event -* EXTERNALLY_TERMINATED - terminated externally, for instance through REST API -* INTERNALLY_TERMINATED - terminated internally, for instance by terminating boundary event - -Among them following states can be triggered externally, for example through REST API or Cockpit: ACTIVE, SUSPENDED, EXTERNALLY_TERMINATED. - -## Query History - -The HistoryService exposes the methods `createHistoricProcessInstanceQuery()`, -`createHistoricVariableInstanceQuery()`, `createHistoricCaseInstanceQuery()`, -`createHistoricActivityInstanceQuery()`, `createHistoricCaseActivityInstanceQuery()`, -`createHistoricDetailQuery()`, -`createHistoricTaskInstanceQuery()`, -`createHistoricIncidentQuery()`, -`createUserOperationLogQuery()`, -`createHistoricJobLogQuery()`, -`createHistoricDecisionInstanceQuery()`, -`createHistoricBatchQuery()`, -`createHistoricExternalTaskLogQuery` and `createHistoricIdentityLinkLogQuery()` -which can be used for querying history. - -Below are a few examples which show some of the possibilities of the query API for history. Full description of the possibilities can be found in the Javadocs, in the `org.camunda.bpm.engine.history` package. - -**HistoricProcessInstanceQuery** - -Get the ten `HistoricProcessInstances` that are finished and that took the most time to complete (the longest duration) of all finished processes with definition 'XXX'. - -```java -historyService.createHistoricProcessInstanceQuery() - .finished() - .processDefinitionId("XXX") - .orderByProcessInstanceDuration().desc() - .listPage(0, 10); -``` - -**HistoricCaseInstanceQuery** - -Get the ten `HistoricCaseInstances` that are closed and that took the most time to be closed (the longest duration) of all closed cases with definition 'XXX'. - -```java -historyService.createHistoricCaseInstanceQuery() - .closed() - .caseDefinitionId("XXX") - .orderByCaseInstanceDuration().desc() - .listPage(0, 10); -``` - - -**HistoricActivityInstanceQuery** - -Get the last `HistoricActivityInstance` of type 'serviceTask' that has been finished in any process that uses the processDefinition with id 'XXX'. - -``` java -historyService.createHistoricActivityInstanceQuery() - .activityType("serviceTask") - .processDefinitionId("XXX") - .finished() - .orderByHistoricActivityInstanceEndTime().desc() - .listPage(0, 1); -``` - -**HistoricCaseActivityInstanceQuery** - -Get the last `HistoricCaseActivityInstance` that has been finished in any case that uses the caseDefinition with id 'XXX'. - -``` java -historyService.createHistoricCaseActivityInstanceQuery() - .caseDefinitionId("XXX") - .finished() - .orderByHistoricCaseActivityInstanceEndTime().desc() - .listPage(0, 1); -``` - -**HistoricVariableInstanceQuery** - -Get all HistoricVariableInstances from a finished process instance with id 'XXX', ordered by variable name. - -```java -historyService.createHistoricVariableInstanceQuery() - .processInstanceId("XXX") - .orderByVariableName().desc() - .list(); -``` - -**HistoricDetailQuery** - -The next example gets all variable-updates that have been done in process with id '123'. Only HistoricVariableUpdates will be returned by this query. Note that it's possible for a certain variable name to have multiple HistoricVariableUpdate entries, one for each time the variable was updated in the process. You can use orderByTime (the time the variable update was done) or orderByVariableRevision (revision of runtime variable at the time of updating) to find out in what order they occurred. - -```java -historyService.createHistoricDetailQuery() - .variableUpdates() - .processInstanceId("123") - .orderByVariableName().asc() - .list() -``` - -The next example gets all variable updates that were performed on the task with id '123'. This returns all HistoricVariableUpdates for variables that were set on the task (task local variables), and NOT on the process instance. - -```java -historyService.createHistoricDetailQuery() - .variableUpdates() - .taskId("123") - .orderByVariableName().asc() - .list() -``` - -**HistoricTaskInstanceQuery** - -Get the ten HistoricTaskInstances that are finished and that took the most time to complete (the longest duration) of all tasks. - -```java -historyService.createHistoricTaskInstanceQuery() - .finished() - .orderByHistoricTaskInstanceDuration().desc() - .listPage(0, 10); -``` - -Get HistoricTaskInstances that are deleted with a delete reason that contains 'invalid' and that were last assigned to user 'jonny'. - -```java -historyService.createHistoricTaskInstanceQuery() - .finished() - .taskDeleteReasonLike("%invalid%") - .taskAssignee("jonny") - .listPage(0, 10); -``` - -**HistoricIncidentQuery** - -Query for all resolved incidents: - -```java -historyService.createHistoricIncidentQuery() - .resolved() - .list(); -``` - -**UserOperationLogQuery** - -Query for all operations performed by user 'jonny': - -```java -historyService.createUserOperationLogQuery() - .userId("jonny") - .listPage(0, 10); -``` - -**HistoricJobLogQuery** - -Query for successful historic job logs: - -```java -historyService.createHistoricJobLogQuery() - .successLog() - .list(); -``` - -**HistoricDecisionInstanceQuery** - -Get all HistoricDecisionInstances from a decision with key 'checkOrder' ordered by the time when the decision was evaluated. - -```java -historyService.createHistoricDecisionInstanceQuery() - .decisionDefinitionKey("checkOrder") - .orderByEvaluationTime() - .asc() - .list(); -``` - -Get all HistoricDecisionInstances from decisions that were evaluated during the execution of the process instance with id 'XXX'. The HistoricDecisionInstances contains the input values on which the decision was evaluated and the output values of the matched rules. - -```java -historyService.createHistoricDecisionInstanceQuery() - .processInstanceId("XXX") - .includeInputs() - .includeOutputs() - .list(); -``` - -**HistoricBatchQuery** - -Get all historic process instance migration batches ordered by id. - -```java -historyService.createHistoricBatchQuery() - .type(Batch.TYPE_PROCESS_INSTANCE_MIGRATION) - .orderById().desc() - .list(); -``` -**HistoricIdentityLinkLogQuery** - -Query for all identity links that are related to the user 'demo'. - -```java -historyService.createHistoricIdentityLinkLogQuery() - .userId("demo") - .list(); -``` - -**HistoricExternalTaskLogQuery** - -Query for failed historic external task logs: - -```java -historyService.createHistoricExternalTaskLogQuery() - .failureLog() - .list(); -``` - -## History Report - -You can use the reports section to retrieve custom statistics and reports. Currently, we support the following kinds of reports: - -* [Instance Duration Report]({{< relref "#instance-duration-report" >}}) -* [Task Report]({{< relref "#task-report" >}}) -* [Finished Instance Report]({{< relref "#finished-instance-report" >}}) - - - -### Instance Duration Report - -Retrieves a report about the duration of completed process instances, grouped by a specified period. These reports include the maximum, minimum and average duration of all completed process instances, which were started in the specified period. The following code snippet retrieves a report for every month since the engine was started: - -```java -historyService - .createHistoricProcessInstanceReport() - .duration(PeriodUnit.MONTH); -``` - -The supported periods so far are `MONTH` and `QUARTER` from `org.camunda.bpm.engine.query.PeriodUnit`. - -To narrow down the report query, one can use the following methods from ``HistoricProcessInstanceReport``: - -* ``startedBefore``: Only takes historic process instances into account that were started before a given date. -* ``startedAfter``: Only takes historic process instances into account that were started after a given date. -* ``processDefinitionIdIn``: Only takes historic process instances into account for given process definition ids. -* ``processDefinitionKeyIn``: Only takes historic process instances into account for given process definition keys. - -where `startedBefore` and `startedAfter` use `java.util.Date` (deprecated) or `java.util.Calendar` objects for the input. - -For instance, one could query for all historic process instances which were started before now and get their duration: - - ```java -Calendar calendar = Calendar.getInstance(); -historyService.createHistoricProcessInstanceReport() - .startedBefore(calendar.getTime()) - .duration(PeriodUnit.MONTH); - ``` - -### Task Report - -Retrieves a report of completed tasks. For the task report there are two possible report types: count and duration. - -If you use the method `countByProcessDefinitionKey` or `countByTaskName` in the end of your report query, the report contains a list of completed task counts where an entry contains the task name, the definition key of the task, the process definition id, the process definition key, the process definition name and the count of how many tasks were completed for the specified key in a given period. The methods `countByProcessDefinitionKey` and `countByTaskName` then group the count reports according the criterion 'definition key' or 'task name'. To retrieve a task count report grouped by the task name, one could execute the following query: - -```java -historyService - .createHistoricTaskInstanceReport() - .countByTaskName(); -``` - -If the report type is set to duration, the report contains a minimum, maximum and average duration value of all completed task instances in a given period. - -```java -historyService - .createHistoricTaskInstanceReport() - .duration(PeriodUnit.MONTH); -``` - -The supported period times and the confinement of the query works analogously to [Instance Duration Report]({{< relref "#instance-duration-report" >}}). - -### Finished Instance Report - -Retrieves a report of finished process, decision or case instances. The report helps the user to tune the history time to live for definitions. They can see a summary of the historic data which can be cleaned after history cleanup. The output fields are definition id, key, name, version, count of the finished instances and count of the 'cleanable' instances. - -```java -historyService - .createHistoricFinishedProcessInstanceReport() - .list(); - -historyService - .createHistoricFinishedDecisionInstanceReport() - .list(); - -historyService - .createHistoricFinishedCaseInstanceReport() - .list(); -``` - -## Partially Sorting History Events by Their Occurrence - -Sometimes you want to sort history events in the order in which they -occurred. Please note that timestamps cannot be used for that. - -Most history events contain a timestamp which marks the point in time at which the action signified -by the event occurred. However, this timestamp can, in general, not be used for sorting the history -events. The reason is that the process engine can be run on multiple cluster nodes: - -* on a single machine, the clock may change due to network sync at runtime, -* in a cluster, events happening in a single process instance may be generated on different nodes - among which the clock may not be synced accurately down to nanoseconds. - -To work around this, the Camunda engine generates sequence numbers which can be used to *partially* -sort history events by their occurrence. - -At a BPMN level this means that instances of concurrent activities (example: activities on different -parallel branches after a parallel gateway) cannot be compared to each other. Instances of -activities that are part of happens-before relation at the BPMN level will be ordered in respect to -that relation. - -Example: - -```java -List result = historyService - .createHistoricActivityInstanceQuery() - .processInstanceId("someProcessInstanceId") - .orderPartiallyByOccurrence() - .asc() - .list(); -``` - -Please note the returned list of historic activity instances in the example is -only partially sorted, as explained above. It guarantees that related -activity instances are sorted by their occurrence. The ordering of unrelated -activity instances is arbitrary and is not guaranteed. - - -# User Operation Log - -The user operation log contains entries for many API operations and can be used for auditing purposes. It provides data on what kind of operations are performed as well as details on the changes involved in the operation. Operations are logged when the operation is performed in the context of a logged in user. To use the operation log, the process engine history level must be set to `FULL`. - -## Write Log Entries Regardless of User Authentication Context - -If it is desired that operations are logged regardless whether they are performed in the context of a logged in user or not, then the process engine configuration flag named `restrictUserOperationLogToAuthenticatedUsers` can be set to `false`. - -## Access the User Operation Log - -The user operation log can be accessed via the Java API. The history service can be used to execute a `UserOperationLogQuery` by calling `historyService.createUserOperationLogQuery().execute()`. The query can be restricted with various filtering options. The query is also {{< restref page="queryUserOperationEntries" text="exposed in the REST API" tag="Historic-User-Operation-Log" >}}. - - -## User Operation Log Entries - -The log consists of *operations* and *entries*. An operation corresponds to one performed action and consists of multiple entries, at least one. Entries contain the detailed changes being part of the operation. When making a user operation log query, the returned entities are of type `UserOperationLogEntry`, corresponding to entries. All entries of one operation are linked by an operation id. - -A user operation log entry has the following properties: - -* **Operation ID**: A generated id that uniquely identifies a performed operation. Multiple log entries that are part of one operation reference the same operation ID. -* **Operation Type**: The name of the performed operation. Available operation types are listed in the interface {{< javadocref page="org/camunda/bpm/engine/history/UserOperationLogEntry.html" text="org.camunda.bpm.engine.history.UserOperationLogEntry" >}}. Note that one operation can consist of multiple types, for example a cascading API operation is one user operation, but is split into multiple types of operations. -* **Entity Type**: An identifier of the type of the entity that was addressed by the operation. Available entity types are listed in the class {{< javadocref page="org/camunda/bpm/engine/EntityTypes.html" text="org.camunda.bpm.engine.EntityTypes" >}}. Like the operation type, one operation may address more than one type of entity. -* **Category**: The name of the category the operation is associated with. Available categories are listed in the interface {{< javadocref page="org/camunda/bpm/engine/history/UserOperationLogEntry.html" text="org.camunda.bpm.engine.history.UserOperationLogEntry" >}}. For example, all task related runtime operations like claiming and completing tasks fall into the category {{< javadocref page="org/camunda/bpm/engine/history/UserOperationLogEntry.html#CATEGORY_TASK_WORKER" text="TaskWorker" >}}. -* **Annotation**: An arbitrary text annotation set by a user for auditing reasons. Multiple log entries that belong to an operation have the same annotation. -* **Entity IDs**: A job log entry contains the entity IDs that serve to identify the entities addressed by the operation. For example, an operation log entry on a task contains the id of the task as well as the id of the process instance the task belongs to. As a second example, a log entry for suspending all process instances of a process definition does not contain individual process instance IDs but only the process definition ID. -* **User ID**: The ID of the user who performed the operation. -* **Timestamp**: The time at which the operation was performed. -* **Changed Property**: A user operation may change multiple properties. For example, suspension of a process instance changes the suspension state property. A log entry is created for each changed property involved in an operation. -* **Old Property Value**: The previous value of the changed property. A `null` value either indicates that the property was previously `null` or is not known. -* **New Property Value**: The new value of the changed property. - -## Annotation of User Operation Logs - -User Operation Logs are helpful to audit manual operations. To make it obvious why a certain -operation was performed, sometimes it is not enough to only log technical information (e. g. -timestamp, operation type, etc.) but also add an annotation that puts the operation in the right -business context. - -You can directly pass an annotation for the following operations: - -* [Process Instance Modification][op-log-set-annotation-instance-mod] - -You can also set an annotation to an operation log which is already present: - -An annotation can be set and cleared via Java API: - -```java -String operationId = historyService.createUserOperationLogQuery() - .singleResult() - .getOperationId(); - -String annotation = "Instances restarted due to wrong turn"; -historyService.setAnnotationForOperationLogById(operationId, annotation); - -historyService.clearAnnotationForOperationLogById(operationId); -``` - -**Please note:** Annotations are present on all entries that belong to an operation log. - -Please also see the REST API reference for {{< restref page="setAnnotationUserOperationLog" text="setting" tag="Historic-User-Operation-Log" >}} and -{{< restref page="clearAnnotationUserOperationLog" text="clearing" tag="Historic-User-Operation-Log" >}} annotations. - -## Glossary of Operations Logged in the User Operation Log - -The following describes the operations logged in the user operation log and the entries that are created as part of it: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Entity TypeOperation TypeCategoryProperties
TaskAssignTaskWorker -
    -
  • assignee: The id of the user who was assigned to the task
    • -
-
ClaimTaskWorker -
    -
  • assignee: The id of the user who claimed the task
    • -
-
CompleteTaskWorker -
    -
  • delete: The new delete state, true
    • -
-
CreateTaskWorkerNo additional property is logged
DelegateTaskWorker - When delegating a task, three log entries are created, containing one of the following properties: -
    -
  • delegation: The resulting delegation state, PENDING
    • -
  • owner: The original owner of the task
    • -
  • assignee: The user this task has been assigned to
    • -
-
DeleteTaskWorker -
    -
  • delete: The new delete state, true
    • -
-
ResolveTaskWorker -
    -
  • delegation: The resulting delegation state, RESOLVED
    • -
-
SetOwnerTaskWorker -
    -
  • owner: The new owner of the task
    • -
-
SetPriorityTaskWorker -
    -
  • priority: The new priority of the task
    • -
-
UpdateTaskWorker - The manually changed property of a task, where manually means that a property got directly changed. Claiming a task via the TaskService wouldn't be logged with an update entry, but setting the assignee directly would be. One of the following is possible: -
    -
  • description: The new description of the task
    • -
  • owner: The new owner of the task
    • -
  • assignee: The new assignee to the task
    • -
  • dueDate: The new due date of the task
    • -
-
DeleteHistoryOperator -
    -
  • nrOfInstances: the amount of decision instances that were deleted
    • -
  • async: by default false since the operation can only be performed synchronously
    • -
-
ProcessInstanceCreateOperatorNo additional property is logged
ActivateOperator -
    -
  • suspensionState: The new suspension state, active
    • -
-
DeleteOperator - In case of regular operation: -
    No additional property is logged
- In case of batch operation: -
    -
  • nrOfInstances: the amount of process instances that were deleted
    • -
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • -
  • deleteReason: the reason for deletion
    • -
  • type: history in case of deletion of historic process instances
    • -
-
ModifyProcessInstanceOperator -
    -
  • nrOfInstances: The amount of process instances modified
    • -
  • async: true if modification was performed asynchronously as a batch, false if modification was performed synchronously
    • -
  • processDefinitionVersion: The version of the process definition
    • -
-
SuspendOperator -
    -
  • suspensionState: The new suspension state, suspended
    • -
-
MigrateOperator -
    -
  • processDefinitionId: The id of the process definition that instances are migrated to
    • -
  • nrOfInstances: The amount of process instances migrated
    • -
  • nrOfVariables: The amount of set variables. Only present when variables were set
    • -
  • async: true if migration was performed asynchronously as a batch, false if migration was performed synchronously
    • -
-
RestartProcessInstanceOperator -
    -
  • nrOfInstances: The amount of process instances restarted
    • -
  • async: true if restart was performed asynchronously as a batch, false if restart was performed synchronously
    • -
-
DeleteHistoryOperator -
    -
  • nrOfInstances: the amount of process instances that were deleted
    • -
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • -
  • deleteReason: the reason for deletion. This property exists only if the operation was performed asynchronously
    • -
-
CreateIncidentOperator -
    -
  • incidentType: The type of incident that was created
    • -
  • configuration: The configuration of the incident that was created
    • -
-
ResolveOperator -
    -
  • incidentId: The id of the incident that was resolved
    • -
-
SetRemovalTimeOperator -
    -
  • async: true if operation was performed asynchronously as a batch
    • -
  • nrOfInstances: The amount of updated instances
    • -
  • removalTime: The date of which an instance shall be removed
    • -
  • - mode: CALCULATED_REMOVAL_TIME if the removal time was calculated, - ABSOLUTE_REMOVAL_TIME if the removal time was set explicitly, - CLEARED_REMOVAL_TIME if the removal time was cleared -
    • -
  • - hierarchical: true if the removal time was set across the hiearchy, - false if the hierarchy was neglected -
    • -
-
SetVariablesOperator -
    -
  • async: true if operation was performed asynchronously as a batch
    • -
  • nrOfInstances: The amount of affected instances
    • -
  • nrOfVariables: The amount of set variables
    • -
-
CorrelateMessageOperator -
    -
  • async: true if operation was performed asynchronously as a batch
    • -
  • nrOfInstances: The amount of affected instances
    • -
  • nrOfVariables: The amount of set variables
    • -
  • messageName: The name of the correlated message
    • -
-
IncidentSetAnnotationOperator -
    -
  • incidentId: the id of the annotated incident
    • -
-
ClearAnnotationOperator -
    -
  • incidentId: the id of the annotated incident
    • -
-
IdentityLinkAddUserLinkTaskWorker -
    -
  • candidate: The new candidate user associated
    • -
-
DeleteUserLinkTaskWorker -
    -
  • candidate: The previously associated user
    • -
-
AddGroupLinkTaskWorker -
    -
  • candidate: The new group associated
    • -
-
DeleteGroupLinkTaskWorker -
    -
  • candidate: The previously associated group
    • -
-
AttachmentAddAttachmentTaskWorker -
    -
  • name: The name of the added attachment
    • -
-
DeleteAttachmentTaskWorker -
    -
  • name: The name of the deleted attachment
    • -
-
JobDefinitionActivateJobDefinitionOperator -
    -
  • suspensionState: the new suspension state active
    • -
-
SetPriorityOperator -
    -
  • overridingPriority: the new overriding job priority. Is null, if the priority was cleared.
    • -
-
SuspendJobDefinitionOperator -
    -
  • suspensionState: the new suspension state suspended
    • -
-
ProcessDefinitionActivateProcessDefinitionOperator -
    -
  • suspensionState: the new suspension state active
    • -
-
SuspendProcessDefinitionOperator -
    -
  • suspensionState: the new suspension state suspended
    • -
-
DeleteOperator -
    -
  • cascade: if the value is set to true, then all instances including history are also deleted.
    • -
-
UpdateHistoryTimeToLiveOperator -
    -
  • historyTimeToLive: the new history time to live.
    • -
-
DecisionDefinitionUpdateHistoryTimeToLiveOperator -
    -
  • historyTimeToLive: the new history time to live.
    • -
  • decisionDefinitionId: the id of the decision definition whose history time to live is updated.
    • -
  • decisionDefinitionKey: the key of the decision definition whose history time to live is updated.
    • -
-
EvaluateOperator -
    -
  • decisionDefinitionId: the id of the decision definition that was evaluated.
    • -
  • decisionDefinitionKey: the key of the decision definition that was evaluated.
    • -
-
CaseDefinitionUpdateHistoryTimeToLiveOperator -
    -
  • historyTimeToLive: the new history time to live.
    • -
  • caseDefinitionKey: the key of the case definition whose history time to live is updated.
    • -
-
JobActivateJobOperator -
    -
  • suspensionState: the new suspension state active
    • -
-
SetPriorityOperator -
    -
  • priority: the new priority of the job
    • -
-
SetJobRetriesOperator -
    -
  • retries: the new number of retries
    • -
  • nrOfInstances: the number of jobs that were updated.
    • -
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • -
-
SuspendJobOperator -
    -
  • suspensionState: the new suspension state suspended
    • -
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • -
-
ExecuteOperatorNo additional property is logged
DeleteOperatorNo additional property is logged
SetDueDateOperator -
    -
  • duedate: the new due date of the job
    • -
-
RecalculateDueDateOperator -
    -
  • creationDateBased: if the value is set to true, the new due date was calculated based on the creation date of the job. Otherwise, it was calculated using the date the recalcuation took place.
    • -
  • duedate: the new due date of the job
    • -
-
CreateHistoryCleanupJobsOperator -
    -
  • immediatelyDue: true if the operation was performed immediately, false if the operation was scheduled regularly
    • -
-
VariableModifyVariableOperator/
TaskWorker		No additional property is logged
RemoveVariableOperator/
TaskWorker		No additional property is logged
SetVariableOperator/
TaskWorker		No additional property is logged
DeleteHistoryOperator - In case of single operation: -
    -
  • name: the name of the variable whose history was deleted
    • -
- In case of list operation by process instance: -
    No additional property is logged
-
DeploymentCreateOperator -
    -
  • duplicateFilterEnabled: if the value is set to true, then during the creation of the deployment the given resources have been checked for duplicates in the set of previous deployments. Otherwise, the duplicate filtering has been not executed.
    • -
  • deployChangedOnly: this property is only logged when duplicateFilterEnabled is set to true. If the property value is set to true then only changed resources have been deployed. Otherwise, all resources are redeployed if any resource has changed.
    • -
-
DeleteOperator -
    -
  • cascade: if the value is set to true, then all instances including history are also deleted.
    • -
-
BatchActivateBatchOperator -
    -
  • suspensionState: the new suspension state active
    • -
-
SuspendBatchOperator -
    -
  • suspensionState: the new suspension state suspended
    • -
-
DeleteOperator -
    -
  • cascadeToHistory: true if historic data related to the batch job is deleted as well, false if only the runtime data is deleted.
    • -
-
DeleteHistoryOperatorNo additional property is logged
SetRemovalTimeOperator -
    -
  • async: true if operation was performed asynchronously as a batch
    • -
  • nrOfInstances: The amount of updated instances
    • -
  • removalTime: The date of which an instance shall be removed
    • -
  • - mode: CALCULATED_REMOVAL_TIME if the removal time was calculated, - ABSOLUTE_REMOVAL_TIME if the removal time was set explicitly, - CLEARED_REMOVAL_TIME if the removal time was cleared -
    • -
-
ExternalTaskSetExternalTaskRetriesOperator -
    -
  • retries: the new number of retries
    • -
  • nrOfInstances: the amount of external tasks that were updated
    • -
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • -
-
SetPriorityOperator -
    -
  • priority: the new priority
    • -
-
UnlockOperatorNo additional property is logged
DecisionInstanceDeleteHistoryOperator -
    -
  • nrOfInstances: the amount of decision instances that were deleted
    • -
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • -
  • deleteReason: the reason for deletion. This property exists only if operation was performed asynchronously
    • -
-
SetRemovalTimeOperator -
    -
  • async: true if operation was performed asynchronously as a batch
    • -
  • nrOfInstances: The amount of updated instances
    • -
  • removalTime: The date of which an instance shall be removed
    • -
  • - mode: CALCULATED_REMOVAL_TIME if the removal time was calculated, - ABSOLUTE_REMOVAL_TIME if the removal time was set explicitly, - CLEARED_REMOVAL_TIME if the removal time was cleared -
    • -
  • - hierarchical: true if the removal time was set across the hiearchy, - false if the hierarchy was neglected -
    • -
-
CaseInstanceDeleteHistoryOperator -
    -
  • nrOfInstances: The amount of case instances that were deleted. Only present if executed in bulk delete.
    • -
-
MetricsDeleteOperator -
    -
  • timestamp: The date for which all metrics older than that have been deleted. Only present if specified by the user.
    • -
  • reporter: The reporter for which all metrics reported by it have been deleted. Only present if specified by the user.
    • -
-
TaskMetricsDeleteOperator -
    -
  • timestamp: The date for which all task metrics older than that have been deleted. Only present if specified by the user.
    • -
-
OperationLogSetAnnotationOperator -
    -
  • operationId: the id of the annotated operation log
    • -
-
ClearAnnotationOperator -
    -
  • operationId: the id of the annotated operation log
    • -
-
FilterCreateTaskWorker -
    -
  • filterId: the id of the filter that been created
    • -
-
UpdateTaskWorker -
    -
  • filterId: the id of the filter that been updated
    • -
-
DeleteTaskWorker -
    -
  • filterId: the id of the filter that been deleted
    • -
-
UserCreateAdmin -
    -
  • userId: the id of the user that has been created
    • -
-
UpdateAdmin -
    -
  • userId: the id of the user that has been updated
    • -
-
DeleteAdmin -
    -
  • userId: the id of the user that has been deleted
    • -
-
UnlockAdmin -
    -
  • userId: the id of the user that has been unlocked
    • -
-
GroupCreateAdmin -
    -
  • groupId: the id of the group that has been created
    • -
-
UpdateAdmin -
    -
  • groupId: the id of the group that has been updated
    • -
-
DeleteAdmin -
    -
  • groupId: the id of the group that has been deleted
    • -
-
TenantCreateAdmin -
    -
  • tenantId: the id of the tenant that has been created
    • -
-
UpdateAdmin -
    -
  • tenantId: the id of the tenant that has been updated
    • -
-
DeleteAdmin -
    -
  • tenantId: the id of the tenant that has been deleted
    • -
-
Group membershipCreateAdmin -
    -
  • userId: the id of the user that has been added to the group
    • -
  • groupId: the id of the group that the user has been added to
    • -
-
DeleteAdmin -
    -
  • userId: the id of the user that has been deleted from the group
    • -
  • groupId: the id of the group that the user has been deleted from
    • -
-
TenantMembershipCreateAdmin -
    -
  • tenantId: the id of the tenant that the group or user was associated with
    • -
  • userId: the id of the user that has been associated with the tenant. Is not present if the groupId is set
    • -
  • groupId: the id of the group that has been associated with the tenant. Is not present if the userId is set
    • -
-
DeleteAdmin -
    -
  • tenantId: the id of the tenant that the group or user has been deleted from
    • -
  • userId: the id of the user that has been deleted from the tenant. Is not present if the groupId is set
    • -
  • groupId: the id of the group that has been deleted from the tenant. Is not present if the userId is set
    • -
-
AuthorizationCreateAdmin -
    -
  • permissions: the list of permissions that has been granted or revoked
    • -
  • permissionBits: the permissions bit mask that is persisted with the authorization
    • -
  • type: the type of authorization, can be either 0 (GLOBAL), 1 (GRANT) or 2 (REVOKE)
    • -
  • resource: the name of the resource type
    • -
  • resourceId: The id of the resource. Can be '*' if granted or revoked for all instances of the resource type.
    • -
  • userId: The id of the user the authorization is bound to. Can be '*' if granted or revoked for all users. Is not present when groupId is set.
    • -
  • groupId: The id of the group the authorization is bound to. Is not present when userId is set.
    • -
-
UpdateAdmin -
    -
  • permissions: the list of permissions that has been granted or revoked
    • -
  • permissionBits: the permissions bit mask that is persisted with the authorization
    • -
  • type: the type of authorization, can be either 0 (GLOBAL), 1 (GRANT) or 2 (REVOKE)
    • -
  • resource: the name of the resource type
    • -
  • resourceId: The id of the resource. Can be '*' if granted or revoked for all instances of the resource type.
    • -
  • userId: The id of the user the authorization is bound to. Can be '*' if granted or revoked for all users. Is not present when groupId is set.
    • -
  • groupId: The id of the group the authorization is bound to. Is not present when userId is set.
    • -
-
DeleteAdmin -
    -
  • permissions: the list of permissions that has been granted or revoked
    • -
  • permissionBits: the permissions bit mask that is persisted with the authorization
    • -
  • type: the type of authorization, can be either 0 (GLOBAL), 1 (GRANT) or 2 (REVOKE)
    • -
  • resource: the name of the resource type
    • -
  • resourceId: The id of the resource. Can be '*' if granted or revoked for all instances of the resource type.
    • -
  • userId: The id of the user the authorization is bound to. Can be '*' if granted or revoked for all users. Is not present when groupId is set.
    • -
  • groupId: The id of the group the authorization is bound to. Is not present when userId is set.
    • -
-
PropertyCreateAdmin -
    -
  • name: the name of the property that was created
    • -
-
UpdateAdmin -
    -
  • name: the name of the property that was updated
    • -
-
DeleteAdmin -
    -
  • name: the name of the property that was deleted
    • -
-
- - -# Provide a Custom History Backend - -In order to understand how to provide a custom history backend, it is useful to first look at a more detailed view of the history architecture: - -{{< img src="../img/process-engine-history-architecture.png" title="History Architecture" >}} - -Whenever the state of a runtime entity is changed, the core execution component of the process engine fires History Events. In order to make this flexible, the actual creation of the History Events as well as populating the history events with data from the runtime structures is delegated to the History Event Producer. The producer is handed in the runtime data structures (such as an ExecutionEntity or a TaskEntity), creates a new History Event and populates it with data extracted from the runtime structures. - -The event is next delivered to the History Event Handler which constitutes the *History Backend*. The drawing above contains a logical component named *event transport*. This is supposed to represent the channel between the process engine core component producing the events and the History Event Handler. In the default implementation, events are delivered to the History Event Handler synchronously and inside the same JVM. It is however conceptually possible to send the event stream to a different JVM (maybe running on a different machine) and making delivery asynchronous. A good fit might be a transactional message Queue (JMS). - -Once the event has reached the History Event Handler, it can be processed and stored in some kind of datastore. The default implementation writes events to the History Database so that they can be queried using the History Service. - -Exchanging the History Event Handler with a custom implementation allows users to plug in a custom History Backend. To do so, two main steps are required: - -* Provide a custom implementation of the {{< javadocref page="org/camunda/bpm/engine/impl/history/handler/HistoryEventHandler.html" text="HistoryEventHandler" >}} interface. -* Wire the custom implementation in the process engine configuration. - -{{< note title="Composite History Handling" class="info" >}} - Note that if you provide a custom implementation of the HistoryEventHandler and wire it to the process engine, you override the default DbHistoryEventHandler. The consequence is that the process engine will stop writing to the history database and you will not be able to use the history service for querying the audit log. If you do not want to replace the default behavior but only provide an additional event handler, you can use the class `org.camunda.bpm.engine.impl.history.handler.CompositeHistoryEventHandler` that dispatches events to a collection of handlers. -{{< /note >}} -{{< note title="Spring Boot" class="info" >}} - -Note that providing your custom `HistoryEventHandler` in a Spring Boot Starter environment works slightly differently. By default, the Camunda Spring Boot starter uses a `CompositeHistoryEventHandler` which wraps a list of HistoryEventHandler implementations that you can provide via the `customHistoryEventHandlers` engine configuration property. If you want to override the default `DbHistoryEventHandler`, you have to explicitly set the `enableDefaultDbHistoryEventHandler` engine configuration property to `false`. -{{< /note >}} - - -# Implement a Custom History Level - -To provide a custom history level the interface `org.camunda.bpm.engine.impl.history.HistoryLevel` has to be implemented. The custom history level implementation -then has to be added to the process engine configuration, either by configuration or a process engine plugin. - -```xml - - - - - - - - - - - - - - -``` - -The custom history level has to provide a unique id and name for the new history level. - -```java -public int getId() { - return 42; -} - -public String getName() { - return "custom-history"; -} -``` - -If the history level is enabled, the method - -```java -boolean isHistoryEventProduced(HistoryEventType eventType, Object entity) -``` - -is called for every history event to determine if the event should be saved to the history. The event types used in the -engine can be found in `org.camunda.bpm.engine.impl.history.event.HistoryEventTypes` (see [Javadocs][1]). - -The second argument is the entity for which the event is triggered, e.g., a process instance, activity -instance or variable instance. If the `entity` is null the engine tests if the history level in general -handles such history events. If the method returns `false`, the engine will not generate -any history events of this type again. This means that if your history level only wants to generate the history -event for some instances of an event it must still return `true` if `entity` is `null`. - -Please have a look at this [complete example][2] to get a better overview. - -## Removal Time Inheritance -Historic instances inherit the [removal time]({{< relref "#removal-time" >}}) from the respective historic top-level -instance. If the custom history level is configured in a way, so that the historic top-level instance is not written, -the removal time is not available. - -The following historic instances are considered as top-level instances: - -* Batch instance -* Root process instance -* Root decision instance - -## User Operation Logs and Custom History Level - -The following implementation is required in order to enable User Operation Logs: - -```java -public boolean isHistoryEventProduced(HistoryEventType eventType, Object entity) { - if (eventType.equals(HistoryEventTypes.USER_OPERATION_LOG)){ - return true; - } - ... -} -``` - -# History Cleanup - -When used intensively, the process engine can produce a huge amount of historic data. *History Cleanup* is a feature that removes this data based on configurable time-to-live settings. - -It deletes: - -* Historic process instances plus all related historic data (e.g., historic variable instances, historic task instances, historic instance permissions, all comments and attachments related to them, etc.) -* Historic decision instances plus all related historic data (i.e., historic decision input and output instances) -* Historic case instances plus all related historic data (e.g., historic variable instances, historic task instances, etc.) -* Historic batches plus all related historic data (historic incidents and job logs) - -History cleanup can be triggered manually or scheduled on a regular basis. Only [camunda-admins]({{< ref "/user-guide/process-engine/authorization-service.md#the-camunda-admin-group">}}) have permissions to execute history cleanup manually. - -## History Cleanup by Example - -Assume we have a billing process for which we must keep the history trail for ten years for legal compliance reasons. Then we have a holiday application process for which history data is only relevant for a short time. In order to reduce the amount of data we have to store, we want to quickly remove holiday-related data. - -With history cleanup, we can assign the billing process a history time to live of ten years and the holiday process a history time to live of seven days. History cleanup then makes sure that history data is removed when the time to live has expired. This way, we can selectively keep history data based on its importance for our business. At the same time, we only keep what is necessary in the database. - -Note: The exact time at which data is removed depends on a couple of configuration settings, for example the selected *history cleanup strategy*. The underlying concepts and settings are explained in the following sections. - -## Basic Concepts - -### Cleanable Instances - -The following elements of Camunda history are cleanable: - -* Process Instances -* Decision Instances -* Case Instances -* Batches - -Note that cleaning one such instance always removes all dependent history data along with it. For example, cleaning a process instance removes the historic process instance as well as all historic activity instances, historic task instances, etc. - -{{< note title="Note" class="info" >}} -The history clean up job does not delete historic [timer-start-event]({{< ref "/reference/bpmn20/events/timer-events.md#timer-start-event" >}}) jobs. The reason being that the responsibility of timer-start-event job is to start a process instance, i.e. it does not belong to a process instance. -{{< /note >}} - -### History Time To Live (TTL) - -*History Time To Live* (TTL) defines how long historic data shall remain in the database before it is cleaned up. - -* Process, Case and Decision Instances: TTL can be defined in the XML file of the corresponding definition. This value can furthermore be changed after deployment via Java and REST API. -* Batches: TTL can be defined in the process engine configuration. - -See the [TTL configuration section](#history-time-to-live) for how to set TTL. - -### Instance End Time - -*End Time* is the time when an instance is no longer active. - -* Process Instances: The time when the instance finishes. -* Decision Instances: The time when the decision is evaluated. -* Case Instances: The time when the instance completes. -* Batches: The time when the batch completes. - -The end time is persisted in the corresponding instance tables `ACT_HI_PROCINST`, `ACT_HI_CASEINST`, `ACT_HI_DECINST` and `ACT_HI_BATCH`. - -### Instance Removal Time - -*Removal Time* is the time after which an instance shall be removed. It is computed as `removal time = base time + TTL`. *Base time* is configurable and can be either the start or the end time of an instance. In particular, this means: - -* Process Instances: Base time is either the time when the process instance starts or the time at which it finishes. This is configurable. -* Decision Instances: Base time is the time when the decision is evaluated. -* Case Instances: The removal time concept is not implemented for case instances. -* Batches: Base time is either the time when the batch is created or when the batch is completed. This is configurable. - -For process and decision instances in a hierarchy (e.g. a process instance that is started by another process instance via a BPMN Call Activity), the removal time of all instances is always equal to the removal time of the root instance. - -{{< img src="../img/history-cleanup-process-hierarchy.png" title="History Cleanup" >}} - -The removal time is persisted in *all* history tables. So in case of a process instance, the removal time is present in `ACT_HI_PROCINST` as well as the corresponding secondary entries in `ACT_HI_ACTINST`, `ACT_HI_TASKINST` etc. - -See the [Removal Time Strategy configuration section](#removal-time-strategy) for how to configure if the removal time is based on the start or end time of an instance. - -## Cleanup Strategies - -In order to use history cleanup, you must decide for one of the two avialable history cleanup strategies: *Removal-Time-based* or *End-Time-based* strategy. The *Removal-Time-based* strategy is the default strategy and recommended in most scenarios. The following sections describe the strategies and their differences in detail. See the [Cleanup Strategy configuration section](#cleanup-strategy) for how to configure each of the strategies. - -### Removal-Time-based Strategy - -The *removal-time-based cleanup strategy* deletes data for which the removal time has expired. - -Strengths: - -* Since every history table has a removal time attribute, history cleanup can be done with simple `DELETE FROM WHERE REMOVAL_TIME_ < ` SQL statements. This is much more efficient than end-time-based cleanup. -* Since removal time is consistent for all instances in a hierarchy, a hierarchy is always cleaned up entirely once the removal time has expired. It cannot happen that instances are removed at different times. - -Limitations: - -* Can only remove data for which a removal time is set. This is especially not the case for data which has been created with Camunda versions < 7.10.0. -* Changing the TTL of a definition only applies to history data that is created in the future. It does not dynamically update the removal time of already written history data. However, it is possible to [Set a Removal Time via Batch Operations]({{< ref "/user-guide/process-engine/batch-operations.md#set-a-removal-time">}}). -* History data of case instances is not cleaned up. - -### End-Time-based Strategy - -The *end-time-based cleanup strategy* deletes data whose end time plus TTL has expired. In contrast to the removal-time strategy, this is computed whenever history cleanup is performed. - -Strengths: - -* Changing the TTL of a definition also affects already written history data. -* Can remove data from any Camunda version. - -Limitations: - -* End time is only stored in the instances tables (`ACT_HI_PROCINST`, `ACT_HI_CASEINST`, `ACT_HI_DECINST` and `ACT_HI_BATCH`). To delete data from all history tables, the cleanable instances are first fetched via a `SELECT` statement. Based on that, `DELETE` statements are made for each history table. These statements can involve joins. This is less efficient than removal-time-based history cleanup. -* Instance hierarchies are not cleaned up atomically. Since the individual instances have different end times, they are going to be cleaned up at different times. In consequence, hierarchies can appear partially removed. -* [Historic Instance Permissions] are not cleaned up. -* [History Cleanup Jobs]({{< ref "/user-guide/process-engine/history.md#historycleanupjobs-in-the-historic-job-log">}}) are not removed from the historic job log. - -## Cleanup Internals - -History cleanup is implemented via jobs and performed by the [job executor]({{< ref "/user-guide/process-engine/the-job-executor.md">}}). It therefore competes for execution resources with other jobs, e.g. triggering of BPMN timer events. - -Cleanup execution can be controlled in three ways: - -* Cleanup Window: Determines a time frame in which history cleanup runs. This allows to use the job executor's resources only when there is little load on your system (e.g. at night time or weekends). Default value: No cleanup window is defined. That means that history cleanup is not performed automatically. -* Batch Size: Determines how many instances are cleaned up in one cleanup transaction. Default: 500. -* Degree of Parallelism: Determines how many cleanup jobs can run in parallel. Default: 1 (no parallel execution). - -See the [Cleanup configuration section](#history-cleanup-configuration) for how to set each of these values. - -If there is no cleanable data left, the cleanup job performs exponential backoff between runs to reduce system load. This backoff is limited to a maximum of one hour. Backoff does not apply to manual cleanup runs. - -If cleanup fails, the job executor's [retry mechanism]({{< ref "/user-guide/process-engine/the-job-executor.md#failed-jobs">}}) applies. Once the cleanup job has run out of retries, it is not executed again until one of the following actions is performed: - -* History cleanup is triggered manually -* The process engine is restarted (this resets the number of job retries to the default value) -* The number of job retries is increased manually (e.g. via Java or REST API) - -The history cleanup jobs can be found via the API method `HistoryService#findHistoryCleanupJobs`. - -## History Cleanup Configuration - -### History Time To Live - -#### Process/Decision/Case Definitions - -Process instances are only cleaned up if their corresponding definition has a valid time to live (TTL). -Use the ["historyTimeToLive" extension attribute]({{< ref "/reference/bpmn20/custom-extensions/extension-attributes.md#historytimetolive">}}) of the process definition to define the TTL for all its instances: - -```xml - -... - -``` - -TTL can also be defined in ISO-8601 date format. The function only accepts the notation to define the number of days. - -```xml - -... - -``` - -Once deployed, TTL can be updated via Java API: - -```java - processEngine.getRepositoryService().updateProcessDefinitionHistoryTimeToLive(processDefinitionId, 5); -``` - -Setting the value to `null` clears the TTL. The same can be done via {{< restref page="updateHistoryTimeToLiveByProcessDefinitionKeyAndTenantId" text="REST API" tag="Process-Definition" >}}. - -For decision and case definitions, TTL can be defined in a similar way. - -In case you want to provide an engine-wide default TTL for all process, decision and case definitions, -use the ["historyTimeToLive" attribute]({{< ref "/reference/deployment-descriptors/tags/process-engine.md#historytimetolive">}}) -of the process engine configuration. This value is applied as the default whenever new definitions without TTL are deployed. Note that it therefore does not change the TTL of already deployed definitions. Use the API method given above to change TTL in this case. - -#### Batches - -TTL for batches can be defined via attribute of the process engine configuration. - -```xml - -P5D -``` - -The `batchOperationsForHistoryCleanup` property can be configured in Spring based application or via custom [Process Engine Plugins]({{< ref "/user-guide/process-engine/process-engine-plugins.md">}}). It defines history time to live for each specific historic batch operation. - -```xml - - - - - - - - - - - - - - - - - - - - -``` - -If the specific TTL is not set for a batch operation type, then the option `batchOperationHistoryTimeToLive` applies. - -#### Job Logs - -A history cleanup is always performed by executing a history cleanup job. As with all other jobs, the history cleanup job -will produce events that are logged in the historic job log. By default, those entries will stay in the log indefinitely -and cleanup must be configured explicitly. Please note that this only works for the [removal-time based history cleanup strategy]({{< ref "/user-guide/process-engine/history.md#removal-time-strategy">}}). - -The `historyCleanupJobLogTimeToLive` property can be used to define a TTL for historic job log entries produced by -history cleanup jobs. The property accepts values in the ISO-8601 date format. Note that only the notation to define a number of days is allowed. - -```xml -P5D -``` - -#### Task Metrics - -The process engine reports [runtime metrics]({{< ref "/user-guide/process-engine/metrics.md">}}) to the database that can help draw conclusions about usage, load, and performance of the BPM platform. -With every assignment of a user task, the related task worker is stored as a pseudonymized, fixed-length value in the `ACT_RU_TASK_METER_LOG` table together with a timestamp. Cleanup for this data needs to -be configured explicitly if needed. - -The `taskMetricsTimeToLive` property can be used to define a TTL for task metrics entries produced by user task assignments. -The property accepts values in the ISO-8601 date format. Note that only the notation to define a number of days is allowed. - -```xml -P540D -``` - -{{< note title="Heads Up!" class="warning" >}} -If you are an enterprise customer, your license agreement might require you to report some metrics annually. Please store task metrics from `ACT_RU_TASK_METER_LOG` for at least 18 months until they were reported. -{{< /note >}} - -### Cleanup Window - -For automated history cleanup on a regular basis, a batch window must be configured - the period of time during the day when the cleanup is to run. - -Use the following engine configuration properties to define a batch window for every day of the week: - -```xml -20:00 -06:00 -``` - -Cleanup can also be scheduled individually for each day of the week (e.g. run cleanup only on weekends): - -```xml - -20:00 -06:00 - - -06:00 -06:00 -06:00 -06:00 -``` - -By default, no cleanup window is configured. In that case, history cleanup is not performed automatically. - -See the [engine configuration reference][configuration-options] for a complete list of all parameters. - -### Cleanup Strategy - -Removal-time-based or end-time-based cleanup can be selected as follows: - -```xml -removalTimeBased -``` - -Valid values are `removalTimeBased` and `endTimeBased`. `removalTimeBased` is the default. - -### Removal-Time Strategy - -Removal time is defined per instance as `removal time = base time + TTL`. `base time` can be either the start or end time of the instance in case of process instances. This can be configured in the process engine configuration as follows: - -```xml -end -``` - -Valid values are `start`, `end` and `none`. `end` is the default value and the recommended option. `start` is a bit more efficient when the process engine populates the history tables, because it does not have to make extra `UPDATE` statements when an instance finishes. - -**Note:**: With `historyRemovalTimeStrategy` set to `start`, it is possible to delete historic data of running process instances. When a process is started the removal time will be calculated (start+TTL) and will be set for all the activities of the process. As soon as removal time is reached data from historic tables gets cleaned up irrespective of whether the instance is running or completed. This may lead to the removal of the historic data before the process instance is finished resulting in no available history in Cockpit or history tables. A mitigation strategy is to choose a longer TTL value or set `historyRemovalTimeStrategy` to `end`. - -{{< note title="Heads-up!" class="info" >}} -The calculation of the removal time can be enabled independently of the selected cleanup strategy of the process engine. -This allows to perform a custom cleanup procedure outside the process engine by leveraging database capabilities (e.g. via table partitioning by removal time). -{{< /note >}} - -### Parallel Execution - -The degree of parallel execution for history cleanup can be defined in the engine configuration as follows: - -```xml -4 -``` - -Valid values are integers from 1 to 8. 1 is the default value. - -This property specifies the number of jobs used for history cleanup. In consequence, this value determines how many job executor threads and database connections may be busy with history cleanup at once. Choosing a high value can make cleanup faster, but may steal resources from other tasks the engine and database have to perform. - -### Cleanup Batch Size - -The number of instances that are removed in one cleanup transaction can be set as follows: - -```xml -100 -``` - -The default (and maximum) value is 500. Reduce it if you notice transaction timeouts during history cleanup. - -### Clustered Cleanup - -In a multi-engine setup, you can configure whether a specific engine should participate in history cleanup or not. -Please make sure that the same cleanup execution configuration (window, batch size, degree of parallelism) is present -on all participating nodes. - -#### Cleanup Execution Participation per Node - -Sometimes it is necessary to exclude some nodes in a multi-engine setup from performing history cleanup execution, -e. g. to reduce the load on some nodes. - -You can disable the history cleanup execution for each node with the following flag: -```xml -false -``` - -When you exclude a node from executing history cleanup, you don't need to specify the configuration properties -related to the cleanup execution since the particular node ignores them. - -**Please Note:** The history cleanup configuration properties that are unrelated to the cleanup execution (e.g., -time to live, removal time strategy) still need to be defined among all nodes. - -[configuration-options]: {{< ref "/reference/deployment-descriptors/tags/process-engine.md#history-cleanup-configuration-parameters">}} -[1]: http://docs.camunda.org/latest/api-references/javadoc/org/camunda/bpm/engine/impl/history/event/HistoryEventTypes.html -[2]: https://github.com/camunda/camunda-bpm-examples/tree/master/process-engine-plugin/custom-history-level -[op-log-set-annotation-instance-mod]: {{< ref "/user-guide/process-engine/process-instance-modification.md#annotation" >}} -[Historic Instance Permissions]: {{< ref "/user-guide/process-engine/authorization-service.md#historic-instance-permissions" >}} diff --git a/content/user-guide/process-engine/history/_index.md b/content/user-guide/process-engine/history/_index.md new file mode 100644 index 000000000..577d4ba0a --- /dev/null +++ b/content/user-guide/process-engine/history/_index.md @@ -0,0 +1,19 @@ +--- + +title: 'History' +weight: 140 + +menu: + main: + identifier: "user-guide-process-engine-history" + parent: "user-guide-process-engine" + +--- + +The History Event Stream provides audit information about executed process instances. + +{{< img src="../img/process-engine-history.png" title="Process Engine History" >}} + +The process engine maintains the state of running process instances inside the database. This includes *writing* (1.) the state of a process instance to the database as it reaches a wait state and *reading* (2.) the state as process execution continues. We call this database the *runtime database*. In addition to maintaining the runtime state, the process engine creates an audit log providing audit information about executed process instances. We call this event stream the *history event stream* (3.). The individual events which make up this event stream are called *History Events* and contain data about executed process instances, activity instances, changed process variables and so forth. In the default configuration, the process engine will simply write (4.) this event stream to the *history database*. The `HistoryService` API allows querying this database (5.). The history database and the history service are optional components; if the history event stream is not logged to the history database or if the user chooses to log events to a different database, the process engine is still able to work and it is still able to populate the history event stream. This is possible because the BPMN 2.0 Core Engine component does not read state from the history database. It is also possible to configure the amount of data logged, using the `historyLevel` setting in the process engine configuration. + +Since the process engine does not rely on the presence of the history database for generating the history event stream, it is possible to provide different backends for storing the history event stream. The default backend is the `DbHistoryEventHandler` which logs the event stream to the history database. It is possible to exchange the backend and provide a custom storage mechanism for the history event log. diff --git a/content/user-guide/process-engine/history/custom-implementation.md b/content/user-guide/process-engine/history/custom-implementation.md new file mode 100644 index 000000000..06bab4c83 --- /dev/null +++ b/content/user-guide/process-engine/history/custom-implementation.md @@ -0,0 +1,119 @@ +--- + +title: 'Custom implementation' +weight: 40 + +menu: + main: + identifier: "user-guide-process-engine-custom-implementation" + parent: "user-guide-process-engine-history" + +--- + +## Provide a custom history backend + +In order to understand how to provide a custom history backend, it is useful to first look at a more detailed view of the history architecture: + +{{< img src="../../img/process-engine-history-architecture.png" title="History Architecture" >}} + +Whenever the state of a runtime entity is changed, the core execution component of the process engine fires History Events. In order to make this flexible, the actual creation of the History Events as well as populating the history events with data from the runtime structures is delegated to the History Event Producer. The producer is handed in the runtime data structures (such as an ExecutionEntity or a TaskEntity), creates a new History Event and populates it with data extracted from the runtime structures. + +The event is next delivered to the History Event Handler which constitutes the *History Backend*. The drawing above contains a logical component named *event transport*. This is supposed to represent the channel between the process engine core component producing the events and the History Event Handler. In the default implementation, events are delivered to the History Event Handler synchronously and inside the same JVM. It is however conceptually possible to send the event stream to a different JVM (maybe running on a different machine) and making delivery asynchronous. A good fit might be a transactional message Queue (JMS). + +Once the event has reached the History Event Handler, it can be processed and stored in some kind of datastore. The default implementation writes events to the History Database so that they can be queried using the History Service. + +Exchanging the History Event Handler with a custom implementation allows users to plug in a custom History Backend. To do so, two main steps are required: + +* Provide a custom implementation of the {{< javadocref page="org/camunda/bpm/engine/impl/history/handler/HistoryEventHandler.html" text="HistoryEventHandler" >}} interface. +* Wire the custom implementation in the process engine configuration. + +{{< note title="Composite History Handling" class="info" >}} + Note that if you provide a custom implementation of the HistoryEventHandler and wire it to the process engine, you override the default DbHistoryEventHandler. The consequence is that the process engine will stop writing to the history database and you will not be able to use the history service for querying the audit log. If you do not want to replace the default behavior but only provide an additional event handler, you can use the class `org.camunda.bpm.engine.impl.history.handler.CompositeHistoryEventHandler` that dispatches events to a collection of handlers. +{{< /note >}} +{{< note title="Spring Boot" class="info" >}} + +Note that providing your custom `HistoryEventHandler` in a Spring Boot Starter environment works slightly differently. By default, the Camunda Spring Boot starter uses a `CompositeHistoryEventHandler` which wraps a list of HistoryEventHandler implementations that you can provide via the `customHistoryEventHandlers` engine configuration property. If you want to override the default `DbHistoryEventHandler`, you have to explicitly set the `enableDefaultDbHistoryEventHandler` engine configuration property to `false`. +{{< /note >}} + +## Implement a custom history level + +To provide a custom history level the interface `org.camunda.bpm.engine.impl.history.HistoryLevel` has to be implemented. The custom history level implementation +then has to be added to the process engine configuration, either by configuration or a process engine plugin. + +```xml + + + + + + + + + + + + + + +``` + +The custom history level has to provide a unique id and name for the new history level. + +```java +public int getId() { + return 42; +} + +public String getName() { + return "custom-history"; +} +``` + +If the history level is enabled, the method + +```java +boolean isHistoryEventProduced(HistoryEventType eventType, Object entity) +``` + +is called for every history event to determine if the event should be saved to the history. The event types used in the +engine can be found in `org.camunda.bpm.engine.impl.history.event.HistoryEventTypes` (see [Javadocs][1]). + +The second argument is the entity for which the event is triggered, e.g., a process instance, activity +instance or variable instance. If the `entity` is null the engine tests if the history level in general +handles such history events. If the method returns `false`, the engine will not generate +any history events of this type again. This means that if your history level only wants to generate the history +event for some instances of an event it must still return `true` if `entity` is `null`. + +Please have a look at this [complete example][2] to get a better overview. + +### Removal time inheritance +Historic instances inherit the [removal time]({{< relref "#removal-time" >}}) from the respective historic top-level +instance. If the custom history level is configured in a way, so that the historic top-level instance is not written, +the removal time is not available. + +The following historic instances are considered as top-level instances: + +* Batch instance +* Root process instance +* Root decision instance + +### User operation logs and custom history level + +The following implementation is required in order to enable User Operation Logs: + +```java +public boolean isHistoryEventProduced(HistoryEventType eventType, Object entity) { + if (eventType.equals(HistoryEventTypes.USER_OPERATION_LOG)){ + return true; + } + ... +} +``` + + + + +[1]: http://docs.camunda.org/latest/api-references/javadoc/org/camunda/bpm/engine/impl/history/event/HistoryEventTypes.html +[2]: https://github.com/camunda/camunda-bpm-examples/tree/master/process-engine-plugin/custom-history-level \ No newline at end of file diff --git a/content/user-guide/process-engine/history/history-cleanup.md b/content/user-guide/process-engine/history/history-cleanup.md new file mode 100644 index 000000000..860a2bab3 --- /dev/null +++ b/content/user-guide/process-engine/history/history-cleanup.md @@ -0,0 +1,351 @@ +--- + +title: 'History cleanup' +weight: 30 + +menu: + main: + identifier: "user-guide-process-engine-history-cleanup" + parent: "user-guide-process-engine-history" + +--- + + +When used intensively, the process engine can produce a huge amount of historic data. *History Cleanup* is a feature that removes this data based on configurable time-to-live settings. + +It deletes: + +* Historic process instances plus all related historic data (e.g., historic variable instances, historic task instances, historic instance permissions, all comments and attachments related to them, etc.) +* Historic decision instances plus all related historic data (i.e., historic decision input and output instances) +* Historic case instances plus all related historic data (e.g., historic variable instances, historic task instances, etc.) +* Historic batches plus all related historic data (historic incidents and job logs) + +History cleanup can be triggered manually or scheduled on a regular basis. Only [camunda-admins]({{< ref "/user-guide/process-engine/authorization-service.md#the-camunda-admin-group">}}) have permissions to execute history cleanup manually. + +## Use case example + +Assume we have a billing process for which we must keep the history trail for ten years for legal compliance reasons. Then we have a holiday application process for which history data is only relevant for a short time. In order to reduce the amount of data we have to store, we want to quickly remove holiday-related data. + +With history cleanup, we can assign the billing process a history time to live of ten years and the holiday process a history time to live of seven days. History cleanup then makes sure that history data is removed when the time to live has expired. This way, we can selectively keep history data based on its importance for our business. At the same time, we only keep what is necessary in the database. + +Note: The exact time at which data is removed depends on a couple of configuration settings, for example the selected *history cleanup strategy*. The underlying concepts and settings are explained in the following sections. + +## Basic concepts + +### Cleanable instances + +The following elements of Camunda history are cleanable: + +* Process Instances +* Decision Instances +* Case Instances +* Batches + +Note that cleaning one such instance always removes all dependent history data along with it. For example, cleaning a process instance removes the historic process instance as well as all historic activity instances, historic task instances, etc. + +{{< note title="Note" class="info" >}} +The history clean up job does not delete historic [timer-start-event]({{< ref "/reference/bpmn20/events/timer-events.md#timer-start-event" >}}) jobs. The reason being that the responsibility of timer-start-event job is to start a process instance, i.e. it does not belong to a process instance. +{{< /note >}} + +### History Time To Live (TTL) + +*History Time To Live* (TTL) defines how long historic data shall remain in the database before it is cleaned up. + +* Process, Case and Decision Instances: TTL can be defined in the XML file of the corresponding definition. This value can furthermore be changed after deployment via Java and REST API. +* Batches: TTL can be defined in the process engine configuration. + +See the [TTL configuration section](#history-time-to-live) for how to set TTL. + +### Instance end time + +*End Time* is the time when an instance is no longer active. + +* Process Instances: The time when the instance finishes. +* Decision Instances: The time when the decision is evaluated. +* Case Instances: The time when the instance completes. +* Batches: The time when the batch completes. + +The end time is persisted in the corresponding instance tables `ACT_HI_PROCINST`, `ACT_HI_CASEINST`, `ACT_HI_DECINST` and `ACT_HI_BATCH`. + +### Instance removal time + +*Removal Time* is the time after which an instance shall be removed. It is computed as `removal time = base time + TTL`. *Base time* is configurable and can be either the start or the end time of an instance. In particular, this means: + +* Process Instances: Base time is either the time when the process instance starts or the time at which it finishes. This is configurable. +* Decision Instances: Base time is the time when the decision is evaluated. +* Case Instances: The removal time concept is not implemented for case instances. +* Batches: Base time is either the time when the batch is created or when the batch is completed. This is configurable. + +For process and decision instances in a hierarchy (e.g. a process instance that is started by another process instance via a BPMN Call Activity), the removal time of all instances is always equal to the removal time of the root instance. + +{{< img src="../../img/history-cleanup-process-hierarchy.png" title="History Cleanup" >}} + +The removal time is persisted in *all* history tables. So in case of a process instance, the removal time is present in `ACT_HI_PROCINST` as well as the corresponding secondary entries in `ACT_HI_ACTINST`, `ACT_HI_TASKINST` etc. + +See the [Removal Time Strategy configuration section](#removal-time-strategy) for how to configure if the removal time is based on the start or end time of an instance. + +## Cleanup strategies + +In order to use history cleanup, you must decide for one of the two avialable history cleanup strategies: *Removal-Time-based* or *End-Time-based* strategy. The *Removal-Time-based* strategy is the default strategy and recommended in most scenarios. The following sections describe the strategies and their differences in detail. See the [Cleanup Strategy configuration section](#cleanup-strategy) for how to configure each of the strategies. + +### Removal-time-based strategy + +The *removal-time-based cleanup strategy* deletes data for which the removal time has expired. + +Strengths: + +* Since every history table has a removal time attribute, history cleanup can be done with simple `DELETE FROM
WHERE REMOVAL_TIME_ < ` SQL statements. This is much more efficient than end-time-based cleanup. +* Since removal time is consistent for all instances in a hierarchy, a hierarchy is always cleaned up entirely once the removal time has expired. It cannot happen that instances are removed at different times. + +Limitations: + +* Can only remove data for which a removal time is set. This is especially not the case for data which has been created with Camunda versions < 7.10.0. +* Changing the TTL of a definition only applies to history data that is created in the future. It does not dynamically update the removal time of already written history data. However, it is possible to [Set a Removal Time via Batch Operations]({{< ref "/user-guide/process-engine/batch-operations.md#set-a-removal-time">}}). +* History data of case instances is not cleaned up. + +### End-time-based strategy + +The *end-time-based cleanup strategy* deletes data whose end time plus TTL has expired. In contrast to the removal-time strategy, this is computed whenever history cleanup is performed. + +Strengths: + +* Changing the TTL of a definition also affects already written history data. +* Can remove data from any Camunda version. + +Limitations: + +* End time is only stored in the instances tables (`ACT_HI_PROCINST`, `ACT_HI_CASEINST`, `ACT_HI_DECINST` and `ACT_HI_BATCH`). To delete data from all history tables, the cleanable instances are first fetched via a `SELECT` statement. Based on that, `DELETE` statements are made for each history table. These statements can involve joins. This is less efficient than removal-time-based history cleanup. +* Instance hierarchies are not cleaned up atomically. Since the individual instances have different end times, they are going to be cleaned up at different times. In consequence, hierarchies can appear partially removed. +* [Historic Instance Permissions]({{< ref "/user-guide/process-engine/authorization-service.md#historic-instance-permissions" >}}) are not cleaned up. +* [History Cleanup Jobs]({{< ref "/user-guide/process-engine/history/history-cleanup.md#historycleanupjobs-in-the-historic-job-log">}}) are not removed from the historic job log. + +## Cleanup internals + +History cleanup is implemented via jobs and performed by the [job executor]({{< ref "/user-guide/process-engine/the-job-executor.md">}}). It therefore competes for execution resources with other jobs, e.g. triggering of BPMN timer events. + +Cleanup execution can be controlled in three ways: + +* Cleanup Window: Determines a time frame in which history cleanup runs. This allows to use the job executor's resources only when there is little load on your system (e.g. at night time or weekends). Default value: No cleanup window is defined. That means that history cleanup is not performed automatically. +* Batch Size: Determines how many instances are cleaned up in one cleanup transaction. Default: 500. +* Degree of Parallelism: Determines how many cleanup jobs can run in parallel. Default: 1 (no parallel execution). + +See the [Cleanup configuration section](#configuration) for how to set each of these values. + +If there is no cleanable data left, the cleanup job performs exponential backoff between runs to reduce system load. This backoff is limited to a maximum of one hour. Backoff does not apply to manual cleanup runs. + +If cleanup fails, the job executor's [retry mechanism]({{< ref "/user-guide/process-engine/the-job-executor.md#failed-jobs">}}) applies. Once the cleanup job has run out of retries, it is not executed again until one of the following actions is performed: + +* History cleanup is triggered manually +* The process engine is restarted (this resets the number of job retries to the default value) +* The number of job retries is increased manually (e.g. via Java or REST API) + +The history cleanup jobs can be found via the API method `HistoryService#findHistoryCleanupJobs`. + +## Configuration + +### History Time To Live + +#### Required property + +The history time to live is mandatory, any deployment or re-deployment of any model resource (BPMN, DMN, CMMN) that contains a historyTimeToLive of null will be prevented. Unless explicitly disabled via [process engine configuration]({{< ref "/reference/deployment-descriptors/tags/process-engine.md#enforceHistoryTimeToLive">}}). To define a default TTL for process definitions and decision definitions if no other value is defined check [historyTimeToLive configuration]({{< ref "/reference/deployment-descriptors/tags/process-engine.md#historyTimeToLive">}}). + +#### Process/decision/case definitions + +Process instances are only cleaned up if their corresponding definition has a valid time to live (TTL). +Use the ["historyTimeToLive" extension attribute]({{< ref "/reference/bpmn20/custom-extensions/extension-attributes.md#historytimetolive">}}) of the process definition to define the TTL for all its instances: + +```xml + +... + +``` + +TTL can also be defined in ISO-8601 date format. The function only accepts the notation to define the number of days. + +```xml + +... + +``` + +Once deployed, TTL can be updated via Java API: + +```java + processEngine.getRepositoryService().updateProcessDefinitionHistoryTimeToLive(processDefinitionId, 5); +``` + +Setting the value to `null` clears the TTL. The same can be done via {{< restref page="updateHistoryTimeToLiveByProcessDefinitionKeyAndTenantId" text="REST API" tag="Process-Definition" >}}. + +For decision and case definitions, TTL can be defined in a similar way. + +In case you want to provide an engine-wide default TTL for all process, decision and case definitions, +use the ["historyTimeToLive" attribute]({{< ref "/reference/deployment-descriptors/tags/process-engine.md#historytimetolive">}}) +of the process engine configuration. This value is applied as the default whenever new definitions without TTL are deployed. Note that it therefore does not change the TTL of already deployed definitions. Use the API method given above to change TTL in this case. + +#### Batches + +TTL for batches can be defined via attribute of the process engine configuration. + +```xml + +P5D +``` + +The `batchOperationsForHistoryCleanup` property can be configured in Spring based application or via custom [Process Engine Plugins]({{< ref "/user-guide/process-engine/process-engine-plugins.md">}}). It defines history time to live for each specific historic batch operation. + +```xml + + + + + + + + + + + + + + + + + + + + +``` + +If the specific TTL is not set for a batch operation type, then the option `batchOperationHistoryTimeToLive` applies. + +#### Job logs + +A history cleanup is always performed by executing a history cleanup job. As with all other jobs, the history cleanup job +will produce events that are logged in the historic job log. By default, those entries will stay in the log indefinitely +and cleanup must be configured explicitly. Please note that this only works for the [removal-time based history cleanup strategy]({{< ref "/user-guide/process-engine/history/history-cleanup.md#removal-time-strategy">}}). + +The `historyCleanupJobLogTimeToLive` property can be used to define a TTL for historic job log entries produced by +history cleanup jobs. The property accepts values in the ISO-8601 date format. Note that only the notation to define a number of days is allowed. + +```xml +P5D +``` + +#### Task metrics + +The process engine reports [runtime metrics]({{< ref "/user-guide/process-engine/metrics.md">}}) to the database that can help draw conclusions about usage, load, and performance of the BPM platform. +With every assignment of a user task, the related task worker is stored as a pseudonymized, fixed-length value in the `ACT_RU_TASK_METER_LOG` table together with a timestamp. Cleanup for this data needs to +be configured explicitly if needed. + +The `taskMetricsTimeToLive` property can be used to define a TTL for task metrics entries produced by user task assignments. +The property accepts values in the ISO-8601 date format. Note that only the notation to define a number of days is allowed. + +```xml +P540D +``` + +{{< note title="Heads Up!" class="warning" >}} +If you are an enterprise customer, your license agreement might require you to report some metrics annually. Please store task metrics from `ACT_RU_TASK_METER_LOG` for at least 18 months until they were reported. +{{< /note >}} + +### Cleanup window + +For automated history cleanup on a regular basis, a batch window must be configured - the period of time during the day when the cleanup is to run. + +Use the following engine configuration properties to define a batch window for every day of the week: + +```xml +20:00 +06:00 +``` + +Cleanup can also be scheduled individually for each day of the week (e.g. run cleanup only on weekends): + +```xml + +20:00 +06:00 + + +06:00 +06:00 +06:00 +06:00 +``` + +By default, no cleanup window is configured. In that case, history cleanup is not performed automatically. + +See the [engine configuration reference][configuration-options] for a complete list of all parameters. + +### Cleanup strategy + +Removal-time-based or end-time-based cleanup can be selected as follows: + +```xml +removalTimeBased +``` + +Valid values are `removalTimeBased` and `endTimeBased`. `removalTimeBased` is the default. + +### Removal-time strategy + +Removal time is defined per instance as `removal time = base time + TTL`. `base time` can be either the start or end time of the instance in case of process instances. This can be configured in the process engine configuration as follows: + +```xml +end +``` + +Valid values are `start`, `end` and `none`. `end` is the default value and the recommended option. `start` is a bit more efficient when the process engine populates the history tables, because it does not have to make extra `UPDATE` statements when an instance finishes. + +**Note:**: With `historyRemovalTimeStrategy` set to `start`, it is possible to delete historic data of running process instances. When a process is started the removal time will be calculated (start+TTL) and will be set for all the activities of the process. As soon as removal time is reached data from historic tables gets cleaned up irrespective of whether the instance is running or completed. This may lead to the removal of the historic data before the process instance is finished resulting in no available history in Cockpit or history tables. A mitigation strategy is to choose a longer TTL value or set `historyRemovalTimeStrategy` to `end`. + +{{< note title="Heads-up!" class="info" >}} +The calculation of the removal time can be enabled independently of the selected cleanup strategy of the process engine. +This allows to perform a custom cleanup procedure outside the process engine by leveraging database capabilities (e.g. via table partitioning by removal time). +{{< /note >}} + +### Parallel execution + +The degree of parallel execution for history cleanup can be defined in the engine configuration as follows: + +```xml +4 +``` + +Valid values are integers from 1 to 8. 1 is the default value. + +This property specifies the number of jobs used for history cleanup. In consequence, this value determines how many job executor threads and database connections may be busy with history cleanup at once. Choosing a high value can make cleanup faster, but may steal resources from other tasks the engine and database have to perform. + +### Cleanup batch size + +The number of instances that are removed in one cleanup transaction can be set as follows: + +```xml +100 +``` + +The default (and maximum) value is 500. Reduce it if you notice transaction timeouts during history cleanup. + +### Clustered cleanup + +In a multi-engine setup, you can configure whether a specific engine should participate in history cleanup or not. +Please make sure that the same cleanup execution configuration (window, batch size, degree of parallelism) is present +on all participating nodes. + +#### Cleanup execution participation per node + +Sometimes it is necessary to exclude some nodes in a multi-engine setup from performing history cleanup execution, +e. g. to reduce the load on some nodes. + +You can disable the history cleanup execution for each node with the following flag: +```xml +false +``` + +When you exclude a node from executing history cleanup, you don't need to specify the configuration properties +related to the cleanup execution since the particular node ignores them. + +**Please Note:** The history cleanup configuration properties that are unrelated to the cleanup execution (e.g., +time to live, removal time strategy) still need to be defined among all nodes. + +[configuration-options]: {{< ref "/reference/deployment-descriptors/tags/process-engine.md#history-cleanup-configuration-parameters">}} \ No newline at end of file diff --git a/content/user-guide/process-engine/history/history-configuration.md b/content/user-guide/process-engine/history/history-configuration.md new file mode 100644 index 000000000..448bc11f6 --- /dev/null +++ b/content/user-guide/process-engine/history/history-configuration.md @@ -0,0 +1,426 @@ +--- + +title: 'History configuration' +weight: 10 + +menu: + main: + identifier: "user-guide-process-engine-history-configuration" + parent: "user-guide-process-engine-history" + +--- + + +## Choose a history level + +The history level controls the amount of data the process engine provides via the history event stream. The following settings are available out of the box: + +* `NONE`: no history events are fired. +* `ACTIVITY`: the following events are fired: + * Process Instance START, UPDATE, END, MIGRATE: fired as process instances are being started, updated, ended and migrated + * Case Instance CREATE, UPDATE, CLOSE: fired as case instances are being created, updated and closed + * Activity Instance START, UPDATE, END, MIGRATE: fired as activity instances are being started, updated, ended and migrated + * Case Activity Instance CREATE, UPDATE, END: fired as case activity instances are being created, updated and ended + * Task Instance CREATE, UPDATE, COMPLETE, DELETE, MIGRATE: fired as task instances are being created, updated (i.e., re-assigned, delegated etc.), completed, deleted and migrated. +* `AUDIT`: in addition to the events provided by history level `ACTIVITY`, the following events are fired: + * Variable Instance CREATE, UPDATE, DELETE, MIGRATE: fired as process variables are created, updated, deleted and migrated. The default history backend (DbHistoryEventHandler) writes variable instance events to the historic variable instance database table. Rows in this table are updated as variable instances are updated, meaning that only the last value of a process variable will be available. +* `FULL`: in addition to the events provided by history level `AUDIT`, the following events are fired: + * Form property UPDATE: fired as form properties are being created and/or updated. + * The default history backend (DbHistoryEventHandler) writes historic variable updates to the database. This makes it possible to inspect the intermediate values of a process variable using the history service. + * User Operation Log UPDATE: fired when a user performs an operation like claiming a user task, delegating a user task etc. + * Incidents CREATE, DELETE, RESOLVE, MIGRATE: fired as incidents are being created, deleted, resolved and migrated + * Historic Job Log CREATE, FAILED, SUCCESSFUL, DELETED: fired as a job is being created, a job execution failed or was successful or a job was deleted + * Decision Instance EVALUATE: fired when a decision is evaluated by the DMN engine. + * Batch START, END: fired as batches are being started and ended + * Identity links ADD, DELETE: fired when an identity link is being added, deleted or when an assignee of a user task is set or changed and when the owner of a user task is set or changed. + * Historic External Task Log CREATED, DELETED, FAILED, SUCCESSFUL: fired as an external task has been created, deleted or an external task execution has been reported to fail or succeed. +* `AUTO`: The level `auto` is useful if you are planning to run multiple engines on the same database. In that case, all engines have to use the same history level. Instead of manually keeping your configurations in sync, use the level `auto` and the engine determines the level already configured in the database automatically. If none is found, the default value `audit` is used. Keep in mind: If you are planning to use custom history levels, you have to register the custom levels for every configuration, otherwise an exception is thrown. + +If you need to customize the amount of history events logged, you can provide a custom implementation {{< javadocref page="org/camunda/bpm/engine/impl/history/producer/HistoryEventProducer.html" text="HistoryEventProducer" >}} and wire it in the process engine configuration. + +In case of specific needs, you can also create a [custom history level]({{< ref "/user-guide/process-engine/history/custom-implementation.md#implement-a-custom-history-level">}}). + +## Set the history level + +The history level can be provided as a property in the process engine configuration. Depending on how the process engine is configured, the property can be set using Java code: + +```java +ProcessEngine processEngine = ProcessEngineConfiguration + .createProcessEngineConfigurationFromResourceDefault() + .setHistory(ProcessEngineConfiguration.HISTORY_FULL) + .buildProcessEngine(); +``` + +It can also be set using Spring XML or a deployment descriptor (bpm-platform.xml, processes.xml). When using the Camunda Wildfly Subsystem, the property can be set through Wildfly configuration (standalone.xml, domain.xml). + +```xml +audit +``` + +Note that when using the default history backend, the history level is stored in the database and cannot be changed later. + +{{< note title="History levels and Cockpit" class="info" >}} +[Camunda Cockpit]({{< ref "/webapps/cockpit/_index.md" >}}) web application works best with History Level set to `FULL`. "Lower" History Levels will disable certain history-related features. +{{< /note >}} + + + +## Default history implementation + +The default history database writes History Events to the appropriate database tables. The database tables can then be queried using the `HistoryService` or using the REST API. + + +## History entities + +There are the following History entities, which - in contrast to the runtime data - will also remain present in the DB after process and case instances have been completed: + +* `HistoricProcessInstances` containing information about current and past process instances. +* `HistoricVariableInstances` containing information about the latest state a variable held in a process instance. +* `HistoricCaseInstances` containing information about current and past case instances. +* `HistoricActivityInstances` containing information about a single execution of an activity. +* `HistoricCaseActivityInstances` containing information about a single execution of a case activity. +* `HistoricTaskInstances` containing information about current and past (completed and deleted) task instances. +* `HistoricDetails` containing various kinds of information related to either a historic process instances, an activity instance or a task instance. +* `HistoricIncidents` containing information about current and past (i.e., deleted or resolved) incidents. +* `UserOperationLogEntry` log entry containing information about an operation performed by a user. This is used for logging actions such as creating a new task, completing a task, etc. +* `HistoricJobLog` containing information about the job execution. The log provides details about the lifecycle of a job. +* `HistoricDecisionInstance` containing information about a single evaluation of a decision, including the input and output values. +* `HistoricBatch` containing information about current and past batches. +* `HistoricIdentityLinkLog` containing information about current and past (added, deleted, assignee is set or changed and owner is set or changed) identity links. +* `HistoricExternalTaskLog` containing information about the external log. The log provides details about the lifecycle of an external task. + + +### State of HistoricProcessInstances + +For every process instance process engine will create single record in history database and will keep updating this record during process execution. Every HistoricProcessInstance record can get one of the following states assigned: + +* ACTIVE - running process instance +* SUSPENDED - suspended process instances +* COMPLETED - completed through normal end event +* EXTERNALLY_TERMINATED - terminated externally, for instance through REST API +* INTERNALLY_TERMINATED - terminated internally, for instance by terminating boundary event + +Among them following states can be triggered externally, for example through REST API or Cockpit: ACTIVE, SUSPENDED, EXTERNALLY_TERMINATED. + +### Query history + +The HistoryService exposes the methods `createHistoricProcessInstanceQuery()`, +`createHistoricVariableInstanceQuery()`, `createHistoricCaseInstanceQuery()`, +`createHistoricActivityInstanceQuery()`, `createHistoricCaseActivityInstanceQuery()`, +`createHistoricDetailQuery()`, +`createHistoricTaskInstanceQuery()`, +`createHistoricIncidentQuery()`, +`createUserOperationLogQuery()`, +`createHistoricJobLogQuery()`, +`createHistoricDecisionInstanceQuery()`, +`createHistoricBatchQuery()`, +`createHistoricExternalTaskLogQuery` and `createHistoricIdentityLinkLogQuery()` +which can be used for querying history. + +Below are a few examples which show some of the possibilities of the query API for history. Full description of the possibilities can be found in the Javadocs, in the `org.camunda.bpm.engine.history` package. + +**HistoricProcessInstanceQuery** + +Get the ten `HistoricProcessInstances` that are finished and that took the most time to complete (the longest duration) of all finished processes with definition 'XXX'. + +```java +historyService.createHistoricProcessInstanceQuery() + .finished() + .processDefinitionId("XXX") + .orderByProcessInstanceDuration().desc() + .listPage(0, 10); +``` + +**HistoricCaseInstanceQuery** + +Get the ten `HistoricCaseInstances` that are closed and that took the most time to be closed (the longest duration) of all closed cases with definition 'XXX'. + +```java +historyService.createHistoricCaseInstanceQuery() + .closed() + .caseDefinitionId("XXX") + .orderByCaseInstanceDuration().desc() + .listPage(0, 10); +``` + + +**HistoricActivityInstanceQuery** + +Get the last `HistoricActivityInstance` of type 'serviceTask' that has been finished in any process that uses the processDefinition with id 'XXX'. + +``` java +historyService.createHistoricActivityInstanceQuery() + .activityType("serviceTask") + .processDefinitionId("XXX") + .finished() + .orderByHistoricActivityInstanceEndTime().desc() + .listPage(0, 1); +``` + +**HistoricCaseActivityInstanceQuery** + +Get the last `HistoricCaseActivityInstance` that has been finished in any case that uses the caseDefinition with id 'XXX'. + +``` java +historyService.createHistoricCaseActivityInstanceQuery() + .caseDefinitionId("XXX") + .finished() + .orderByHistoricCaseActivityInstanceEndTime().desc() + .listPage(0, 1); +``` + +**HistoricVariableInstanceQuery** + +Get all HistoricVariableInstances from a finished process instance with id 'XXX', ordered by variable name. + +```java +historyService.createHistoricVariableInstanceQuery() + .processInstanceId("XXX") + .orderByVariableName().desc() + .list(); +``` + +**HistoricDetailQuery** + +The next example gets all variable-updates that have been done in process with id '123'. Only HistoricVariableUpdates will be returned by this query. Note that it's possible for a certain variable name to have multiple HistoricVariableUpdate entries, one for each time the variable was updated in the process. You can use orderByTime (the time the variable update was done) or orderByVariableRevision (revision of runtime variable at the time of updating) to find out in what order they occurred. + +```java +historyService.createHistoricDetailQuery() + .variableUpdates() + .processInstanceId("123") + .orderByVariableName().asc() + .list() +``` + +The next example gets all variable updates that were performed on the task with id '123'. This returns all HistoricVariableUpdates for variables that were set on the task (task local variables), and NOT on the process instance. + +```java +historyService.createHistoricDetailQuery() + .variableUpdates() + .taskId("123") + .orderByVariableName().asc() + .list() +``` + +**HistoricTaskInstanceQuery** + +Get the ten HistoricTaskInstances that are finished and that took the most time to complete (the longest duration) of all tasks. + +```java +historyService.createHistoricTaskInstanceQuery() + .finished() + .orderByHistoricTaskInstanceDuration().desc() + .listPage(0, 10); +``` + +Get HistoricTaskInstances that are deleted with a delete reason that contains 'invalid' and that were last assigned to user 'jonny'. + +```java +historyService.createHistoricTaskInstanceQuery() + .finished() + .taskDeleteReasonLike("%invalid%") + .taskAssignee("jonny") + .listPage(0, 10); +``` + +**HistoricIncidentQuery** + +Query for all resolved incidents: + +```java +historyService.createHistoricIncidentQuery() + .resolved() + .list(); +``` + +**UserOperationLogQuery** + +Query for all operations performed by user 'jonny': + +```java +historyService.createUserOperationLogQuery() + .userId("jonny") + .listPage(0, 10); +``` + +**HistoricJobLogQuery** + +Query for successful historic job logs: + +```java +historyService.createHistoricJobLogQuery() + .successLog() + .list(); +``` + +**HistoricDecisionInstanceQuery** + +Get all HistoricDecisionInstances from a decision with key 'checkOrder' ordered by the time when the decision was evaluated. + +```java +historyService.createHistoricDecisionInstanceQuery() + .decisionDefinitionKey("checkOrder") + .orderByEvaluationTime() + .asc() + .list(); +``` + +Get all HistoricDecisionInstances from decisions that were evaluated during the execution of the process instance with id 'XXX'. The HistoricDecisionInstances contains the input values on which the decision was evaluated and the output values of the matched rules. + +```java +historyService.createHistoricDecisionInstanceQuery() + .processInstanceId("XXX") + .includeInputs() + .includeOutputs() + .list(); +``` + +**HistoricBatchQuery** + +Get all historic process instance migration batches ordered by id. + +```java +historyService.createHistoricBatchQuery() + .type(Batch.TYPE_PROCESS_INSTANCE_MIGRATION) + .orderById().desc() + .list(); +``` +**HistoricIdentityLinkLogQuery** + +Query for all identity links that are related to the user 'demo'. + +```java +historyService.createHistoricIdentityLinkLogQuery() + .userId("demo") + .list(); +``` + +**HistoricExternalTaskLogQuery** + +Query for failed historic external task logs: + +```java +historyService.createHistoricExternalTaskLogQuery() + .failureLog() + .list(); +``` + +### History report + +You can use the reports section to retrieve custom statistics and reports. Currently, we support the following kinds of reports: + +* [Instance Duration Report]({{< relref "#instance-duration-report" >}}) +* [Task Report]({{< relref "#task-report" >}}) +* [Finished Instance Report]({{< relref "#finished-instance-report" >}}) + + + +#### Instance duration report + +Retrieves a report about the duration of completed process instances, grouped by a specified period. These reports include the maximum, minimum and average duration of all completed process instances, which were started in the specified period. The following code snippet retrieves a report for every month since the engine was started: + +```java +historyService + .createHistoricProcessInstanceReport() + .duration(PeriodUnit.MONTH); +``` + +The supported periods so far are `MONTH` and `QUARTER` from `org.camunda.bpm.engine.query.PeriodUnit`. + +To narrow down the report query, one can use the following methods from ``HistoricProcessInstanceReport``: + +* ``startedBefore``: Only takes historic process instances into account that were started before a given date. +* ``startedAfter``: Only takes historic process instances into account that were started after a given date. +* ``processDefinitionIdIn``: Only takes historic process instances into account for given process definition ids. +* ``processDefinitionKeyIn``: Only takes historic process instances into account for given process definition keys. + +where `startedBefore` and `startedAfter` use `java.util.Date` (deprecated) or `java.util.Calendar` objects for the input. + +For instance, one could query for all historic process instances which were started before now and get their duration: + + ```java +Calendar calendar = Calendar.getInstance(); +historyService.createHistoricProcessInstanceReport() + .startedBefore(calendar.getTime()) + .duration(PeriodUnit.MONTH); + ``` + +#### Task report + +Retrieves a report of completed tasks. For the task report there are two possible report types: count and duration. + +If you use the method `countByProcessDefinitionKey` or `countByTaskName` in the end of your report query, the report contains a list of completed task counts where an entry contains the task name, the definition key of the task, the process definition id, the process definition key, the process definition name and the count of how many tasks were completed for the specified key in a given period. The methods `countByProcessDefinitionKey` and `countByTaskName` then group the count reports according the criterion 'definition key' or 'task name'. To retrieve a task count report grouped by the task name, one could execute the following query: + +```java +historyService + .createHistoricTaskInstanceReport() + .countByTaskName(); +``` + +If the report type is set to duration, the report contains a minimum, maximum and average duration value of all completed task instances in a given period. + +```java +historyService + .createHistoricTaskInstanceReport() + .duration(PeriodUnit.MONTH); +``` + +The supported period times and the confinement of the query works analogously to [Instance Duration Report]({{< relref "#instance-duration-report" >}}). + +#### Finished instance report + +Retrieves a report of finished process, decision or case instances. The report helps the user to tune the history time to live for definitions. They can see a summary of the historic data which can be cleaned after history cleanup. The output fields are definition id, key, name, version, count of the finished instances and count of the 'cleanable' instances. + +```java +historyService + .createHistoricFinishedProcessInstanceReport() + .list(); + +historyService + .createHistoricFinishedDecisionInstanceReport() + .list(); + +historyService + .createHistoricFinishedCaseInstanceReport() + .list(); +``` + +### Partially sorting history events by their occurrence + +Sometimes you want to sort history events in the order in which they +occurred. Please note that timestamps cannot be used for that. + +Most history events contain a timestamp which marks the point in time at which the action signified +by the event occurred. However, this timestamp can, in general, not be used for sorting the history +events. The reason is that the process engine can be run on multiple cluster nodes: + +* on a single machine, the clock may change due to network sync at runtime, +* in a cluster, events happening in a single process instance may be generated on different nodes + among which the clock may not be synced accurately down to nanoseconds. + +To work around this, the Camunda engine generates sequence numbers which can be used to *partially* +sort history events by their occurrence. + +At a BPMN level this means that instances of concurrent activities (example: activities on different +parallel branches after a parallel gateway) cannot be compared to each other. Instances of +activities that are part of happens-before relation at the BPMN level will be ordered in respect to +that relation. + +Example: + +```java +List result = historyService + .createHistoricActivityInstanceQuery() + .processInstanceId("someProcessInstanceId") + .orderPartiallyByOccurrence() + .asc() + .list(); +``` + +Please note the returned list of historic activity instances in the example is +only partially sorted, as explained above. It guarantees that related +activity instances are sorted by their occurrence. The ordering of unrelated +activity instances is arbitrary and is not guaranteed. + + + diff --git a/content/user-guide/process-engine/history/user-operation-log.md b/content/user-guide/process-engine/history/user-operation-log.md new file mode 100644 index 000000000..46faf4817 --- /dev/null +++ b/content/user-guide/process-engine/history/user-operation-log.md @@ -0,0 +1,1100 @@ +--- + +title: 'User operation log' +weight: 20 + +menu: + main: + identifier: "user-guide-process-engine-user-operation-log" + parent: "user-guide-process-engine-history" + +--- + + +The user operation log contains entries for many API operations and can be used for auditing purposes. It provides data on what kind of operations are performed as well as details on the changes involved in the operation. Operations are logged when the operation is performed in the context of a logged in user. To use the operation log, the process engine history level must be set to `FULL`. + +## Write log entries regardless of user authentication context + +If it is desired that operations are logged regardless whether they are performed in the context of a logged in user or not, then the process engine configuration flag named `restrictUserOperationLogToAuthenticatedUsers` can be set to `false`. + +## Access the user operation log + +The user operation log can be accessed via the Java API. The history service can be used to execute a `UserOperationLogQuery` by calling `historyService.createUserOperationLogQuery().execute()`. The query can be restricted with various filtering options. The query is also {{< restref page="queryUserOperationEntries" text="exposed in the REST API" tag="Historic-User-Operation-Log" >}}. + + +## User operation log entries + +The log consists of *operations* and *entries*. An operation corresponds to one performed action and consists of multiple entries, at least one. Entries contain the detailed changes being part of the operation. When making a user operation log query, the returned entities are of type `UserOperationLogEntry`, corresponding to entries. All entries of one operation are linked by an operation id. + +A user operation log entry has the following properties: + +* **Operation ID**: A generated id that uniquely identifies a performed operation. Multiple log entries that are part of one operation reference the same operation ID. +* **Operation Type**: The name of the performed operation. Available operation types are listed in the interface {{< javadocref page="org/camunda/bpm/engine/history/UserOperationLogEntry.html" text="org.camunda.bpm.engine.history.UserOperationLogEntry" >}}. Note that one operation can consist of multiple types, for example a cascading API operation is one user operation, but is split into multiple types of operations. +* **Entity Type**: An identifier of the type of the entity that was addressed by the operation. Available entity types are listed in the class {{< javadocref page="org/camunda/bpm/engine/EntityTypes.html" text="org.camunda.bpm.engine.EntityTypes" >}}. Like the operation type, one operation may address more than one type of entity. +* **Category**: The name of the category the operation is associated with. Available categories are listed in the interface {{< javadocref page="org/camunda/bpm/engine/history/UserOperationLogEntry.html" text="org.camunda.bpm.engine.history.UserOperationLogEntry" >}}. For example, all task related runtime operations like claiming and completing tasks fall into the category {{< javadocref page="org/camunda/bpm/engine/history/UserOperationLogEntry.html#CATEGORY_TASK_WORKER" text="TaskWorker" >}}. +* **Annotation**: An arbitrary text annotation set by a user for auditing reasons. Multiple log entries that belong to an operation have the same annotation. +* **Entity IDs**: A job log entry contains the entity IDs that serve to identify the entities addressed by the operation. For example, an operation log entry on a task contains the id of the task as well as the id of the process instance the task belongs to. As a second example, a log entry for suspending all process instances of a process definition does not contain individual process instance IDs but only the process definition ID. +* **User ID**: The ID of the user who performed the operation. +* **Timestamp**: The time at which the operation was performed. +* **Changed Property**: A user operation may change multiple properties. For example, suspension of a process instance changes the suspension state property. A log entry is created for each changed property involved in an operation. +* **Old Property Value**: The previous value of the changed property. A `null` value either indicates that the property was previously `null` or is not known. +* **New Property Value**: The new value of the changed property. + +## Annotation of user operation logs + +User Operation Logs are helpful to audit manual operations. To make it obvious why a certain +operation was performed, sometimes it is not enough to only log technical information (e. g. +timestamp, operation type, etc.) but also add an annotation that puts the operation in the right +business context. + +You can directly pass an annotation for the following operations: + +* [Process Instance Modification][op-log-set-annotation-instance-mod] + +You can also set an annotation to an operation log which is already present: + +An annotation can be set and cleared via Java API: + +```java +String operationId = historyService.createUserOperationLogQuery() + .singleResult() + .getOperationId(); + +String annotation = "Instances restarted due to wrong turn"; +historyService.setAnnotationForOperationLogById(operationId, annotation); + +historyService.clearAnnotationForOperationLogById(operationId); +``` + +**Please note:** Annotations are present on all entries that belong to an operation log. + +Please also see the REST API reference for {{< restref page="setAnnotationUserOperationLog" text="setting" tag="Historic-User-Operation-Log" >}} and +{{< restref page="clearAnnotationUserOperationLog" text="clearing" tag="Historic-User-Operation-Log" >}} annotations. + +## Glossary of operations logged in the user operation log + +The following describes the operations logged in the user operation log and the entries that are created as part of it: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Entity TypeOperation TypeCategoryProperties
TaskAssignTaskWorker +
    +
  • assignee: The id of the user who was assigned to the task
    • +
+
ClaimTaskWorker +
    +
  • assignee: The id of the user who claimed the task
    • +
+
CompleteTaskWorker +
    +
  • delete: The new delete state, true
    • +
+
CreateTaskWorkerNo additional property is logged
DelegateTaskWorker + When delegating a task, three log entries are created, containing one of the following properties: +
    +
  • delegation: The resulting delegation state, PENDING
    • +
  • owner: The original owner of the task
    • +
  • assignee: The user this task has been assigned to
    • +
+
DeleteTaskWorker +
    +
  • delete: The new delete state, true
    • +
+
ResolveTaskWorker +
    +
  • delegation: The resulting delegation state, RESOLVED
    • +
+
SetOwnerTaskWorker +
    +
  • owner: The new owner of the task
    • +
+
SetPriorityTaskWorker +
    +
  • priority: The new priority of the task
    • +
+
UpdateTaskWorker + The manually changed property of a task, where manually means that a property got directly changed. Claiming a task via the TaskService wouldn't be logged with an update entry, but setting the assignee directly would be. One of the following is possible: +
    +
  • description: The new description of the task
    • +
  • owner: The new owner of the task
    • +
  • assignee: The new assignee to the task
    • +
  • dueDate: The new due date of the task
    • +
+
DeleteHistoryOperator +
    +
  • nrOfInstances: the amount of decision instances that were deleted
    • +
  • async: by default false since the operation can only be performed synchronously
    • +
+
ProcessInstanceCreateOperatorNo additional property is logged
ActivateOperator +
    +
  • suspensionState: The new suspension state, active
    • +
+
DeleteOperator + In case of regular operation: +
    No additional property is logged
+ In case of batch operation: +
    +
  • nrOfInstances: the amount of process instances that were deleted
    • +
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • +
  • deleteReason: the reason for deletion
    • +
  • type: history in case of deletion of historic process instances
    • +
+
ModifyProcessInstanceOperator +
    +
  • nrOfInstances: The amount of process instances modified
    • +
  • async: true if modification was performed asynchronously as a batch, false if modification was performed synchronously
    • +
  • processDefinitionVersion: The version of the process definition
    • +
+
SuspendOperator +
    +
  • suspensionState: The new suspension state, suspended
    • +
+
MigrateOperator +
    +
  • processDefinitionId: The id of the process definition that instances are migrated to
    • +
  • nrOfInstances: The amount of process instances migrated
    • +
  • nrOfVariables: The amount of set variables. Only present when variables were set
    • +
  • async: true if migration was performed asynchronously as a batch, false if migration was performed synchronously
    • +
+
RestartProcessInstanceOperator +
    +
  • nrOfInstances: The amount of process instances restarted
    • +
  • async: true if restart was performed asynchronously as a batch, false if restart was performed synchronously
    • +
+
DeleteHistoryOperator +
    +
  • nrOfInstances: the amount of process instances that were deleted
    • +
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • +
  • deleteReason: the reason for deletion. This property exists only if the operation was performed asynchronously
    • +
+
CreateIncidentOperator +
    +
  • incidentType: The type of incident that was created
    • +
  • configuration: The configuration of the incident that was created
    • +
+
ResolveOperator +
    +
  • incidentId: The id of the incident that was resolved
    • +
+
SetRemovalTimeOperator +
    +
  • async: true if operation was performed asynchronously as a batch
    • +
  • nrOfInstances: The amount of updated instances
    • +
  • removalTime: The date of which an instance shall be removed
    • +
  • + mode: CALCULATED_REMOVAL_TIME if the removal time was calculated, + ABSOLUTE_REMOVAL_TIME if the removal time was set explicitly, + CLEARED_REMOVAL_TIME if the removal time was cleared +
    • +
  • + hierarchical: true if the removal time was set across the hiearchy, + false if the hierarchy was neglected +
    • +
+
SetVariablesOperator +
    +
  • async: true if operation was performed asynchronously as a batch
    • +
  • nrOfInstances: The amount of affected instances
    • +
  • nrOfVariables: The amount of set variables
    • +
+
CorrelateMessageOperator +
    +
  • async: true if operation was performed asynchronously as a batch
    • +
  • nrOfInstances: The amount of affected instances
    • +
  • nrOfVariables: The amount of set variables
    • +
  • messageName: The name of the correlated message
    • +
+
IncidentSetAnnotationOperator +
    +
  • incidentId: the id of the annotated incident
    • +
+
ClearAnnotationOperator +
    +
  • incidentId: the id of the annotated incident
    • +
+
IdentityLinkAddUserLinkTaskWorker +
    +
  • candidate: The new candidate user associated
    • +
+
DeleteUserLinkTaskWorker +
    +
  • candidate: The previously associated user
    • +
+
AddGroupLinkTaskWorker +
    +
  • candidate: The new group associated
    • +
+
DeleteGroupLinkTaskWorker +
    +
  • candidate: The previously associated group
    • +
+
AttachmentAddAttachmentTaskWorker +
    +
  • name: The name of the added attachment
    • +
+
DeleteAttachmentTaskWorker +
    +
  • name: The name of the deleted attachment
    • +
+
JobDefinitionActivateJobDefinitionOperator +
    +
  • suspensionState: the new suspension state active
    • +
+
SetPriorityOperator +
    +
  • overridingPriority: the new overriding job priority. Is null, if the priority was cleared.
    • +
+
SuspendJobDefinitionOperator +
    +
  • suspensionState: the new suspension state suspended
    • +
+
ProcessDefinitionActivateProcessDefinitionOperator +
    +
  • suspensionState: the new suspension state active
    • +
+
SuspendProcessDefinitionOperator +
    +
  • suspensionState: the new suspension state suspended
    • +
+
DeleteOperator +
    +
  • cascade: if the value is set to true, then all instances including history are also deleted.
    • +
+
UpdateHistoryTimeToLiveOperator +
    +
  • historyTimeToLive: the new history time to live.
    • +
+
DecisionDefinitionUpdateHistoryTimeToLiveOperator +
    +
  • historyTimeToLive: the new history time to live.
    • +
  • decisionDefinitionId: the id of the decision definition whose history time to live is updated.
    • +
  • decisionDefinitionKey: the key of the decision definition whose history time to live is updated.
    • +
+
EvaluateOperator +
    +
  • decisionDefinitionId: the id of the decision definition that was evaluated.
    • +
  • decisionDefinitionKey: the key of the decision definition that was evaluated.
    • +
+
CaseDefinitionUpdateHistoryTimeToLiveOperator +
    +
  • historyTimeToLive: the new history time to live.
    • +
  • caseDefinitionKey: the key of the case definition whose history time to live is updated.
    • +
+
JobActivateJobOperator +
    +
  • suspensionState: the new suspension state active
    • +
+
SetPriorityOperator +
    +
  • priority: the new priority of the job
    • +
+
SetJobRetriesOperator +
    +
  • retries: the new number of retries
    • +
  • nrOfInstances: the number of jobs that were updated.
    • +
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • +
+
SuspendJobOperator +
    +
  • suspensionState: the new suspension state suspended
    • +
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • +
+
ExecuteOperatorNo additional property is logged
DeleteOperatorNo additional property is logged
SetDueDateOperator +
    +
  • duedate: the new due date of the job
    • +
+
RecalculateDueDateOperator +
    +
  • creationDateBased: if the value is set to true, the new due date was calculated based on the creation date of the job. Otherwise, it was calculated using the date the recalcuation took place.
    • +
  • duedate: the new due date of the job
    • +
+
CreateHistoryCleanupJobsOperator +
    +
  • immediatelyDue: true if the operation was performed immediately, false if the operation was scheduled regularly
    • +
+
VariableModifyVariableOperator/
TaskWorker		No additional property is logged
RemoveVariableOperator/
TaskWorker		No additional property is logged
SetVariableOperator/
TaskWorker		No additional property is logged
DeleteHistoryOperator + In case of single operation: +
    +
  • name: the name of the variable whose history was deleted
    • +
+ In case of list operation by process instance: +
    No additional property is logged
+
DeploymentCreateOperator +
    +
  • duplicateFilterEnabled: if the value is set to true, then during the creation of the deployment the given resources have been checked for duplicates in the set of previous deployments. Otherwise, the duplicate filtering has been not executed.
    • +
  • deployChangedOnly: this property is only logged when duplicateFilterEnabled is set to true. If the property value is set to true then only changed resources have been deployed. Otherwise, all resources are redeployed if any resource has changed.
    • +
+
DeleteOperator +
    +
  • cascade: if the value is set to true, then all instances including history are also deleted.
    • +
+
BatchActivateBatchOperator +
    +
  • suspensionState: the new suspension state active
    • +
+
SuspendBatchOperator +
    +
  • suspensionState: the new suspension state suspended
    • +
+
DeleteOperator +
    +
  • cascadeToHistory: true if historic data related to the batch job is deleted as well, false if only the runtime data is deleted.
    • +
+
DeleteHistoryOperatorNo additional property is logged
SetRemovalTimeOperator +
    +
  • async: true if operation was performed asynchronously as a batch
    • +
  • nrOfInstances: The amount of updated instances
    • +
  • removalTime: The date of which an instance shall be removed
    • +
  • + mode: CALCULATED_REMOVAL_TIME if the removal time was calculated, + ABSOLUTE_REMOVAL_TIME if the removal time was set explicitly, + CLEARED_REMOVAL_TIME if the removal time was cleared +
    • +
+
ExternalTaskSetExternalTaskRetriesOperator +
    +
  • retries: the new number of retries
    • +
  • nrOfInstances: the amount of external tasks that were updated
    • +
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • +
+
SetPriorityOperator +
    +
  • priority: the new priority
    • +
+
UnlockOperatorNo additional property is logged
DecisionInstanceDeleteHistoryOperator +
    +
  • nrOfInstances: the amount of decision instances that were deleted
    • +
  • async: true if operation was performed asynchronously as a batch, false if operation was performed synchronously
    • +
  • deleteReason: the reason for deletion. This property exists only if operation was performed asynchronously
    • +
+
SetRemovalTimeOperator +
    +
  • async: true if operation was performed asynchronously as a batch
    • +
  • nrOfInstances: The amount of updated instances
    • +
  • removalTime: The date of which an instance shall be removed
    • +
  • + mode: CALCULATED_REMOVAL_TIME if the removal time was calculated, + ABSOLUTE_REMOVAL_TIME if the removal time was set explicitly, + CLEARED_REMOVAL_TIME if the removal time was cleared +
    • +
  • + hierarchical: true if the removal time was set across the hiearchy, + false if the hierarchy was neglected +
    • +
+
CaseInstanceDeleteHistoryOperator +
    +
  • nrOfInstances: The amount of case instances that were deleted. Only present if executed in bulk delete.
    • +
+
MetricsDeleteOperator +
    +
  • timestamp: The date for which all metrics older than that have been deleted. Only present if specified by the user.
    • +
  • reporter: The reporter for which all metrics reported by it have been deleted. Only present if specified by the user.
    • +
+
TaskMetricsDeleteOperator +
    +
  • timestamp: The date for which all task metrics older than that have been deleted. Only present if specified by the user.
    • +
+
OperationLogSetAnnotationOperator +
    +
  • operationId: the id of the annotated operation log
    • +
+
ClearAnnotationOperator +
    +
  • operationId: the id of the annotated operation log
    • +
+
FilterCreateTaskWorker +
    +
  • filterId: the id of the filter that been created
    • +
+
UpdateTaskWorker +
    +
  • filterId: the id of the filter that been updated
    • +
+
DeleteTaskWorker +
    +
  • filterId: the id of the filter that been deleted
    • +
+
UserCreateAdmin +
    +
  • userId: the id of the user that has been created
    • +
+
UpdateAdmin +
    +
  • userId: the id of the user that has been updated
    • +
+
DeleteAdmin +
    +
  • userId: the id of the user that has been deleted
    • +
+
UnlockAdmin +
    +
  • userId: the id of the user that has been unlocked
    • +
+
GroupCreateAdmin +
    +
  • groupId: the id of the group that has been created
    • +
+
UpdateAdmin +
    +
  • groupId: the id of the group that has been updated
    • +
+
DeleteAdmin +
    +
  • groupId: the id of the group that has been deleted
    • +
+
TenantCreateAdmin +
    +
  • tenantId: the id of the tenant that has been created
    • +
+
UpdateAdmin +
    +
  • tenantId: the id of the tenant that has been updated
    • +
+
DeleteAdmin +
    +
  • tenantId: the id of the tenant that has been deleted
    • +
+
Group membershipCreateAdmin +
    +
  • userId: the id of the user that has been added to the group
    • +
  • groupId: the id of the group that the user has been added to
    • +
+
DeleteAdmin +
    +
  • userId: the id of the user that has been deleted from the group
    • +
  • groupId: the id of the group that the user has been deleted from
    • +
+
TenantMembershipCreateAdmin +
    +
  • tenantId: the id of the tenant that the group or user was associated with
    • +
  • userId: the id of the user that has been associated with the tenant. Is not present if the groupId is set
    • +
  • groupId: the id of the group that has been associated with the tenant. Is not present if the userId is set
    • +
+
DeleteAdmin +
    +
  • tenantId: the id of the tenant that the group or user has been deleted from
    • +
  • userId: the id of the user that has been deleted from the tenant. Is not present if the groupId is set
    • +
  • groupId: the id of the group that has been deleted from the tenant. Is not present if the userId is set
    • +
+
AuthorizationCreateAdmin +
    +
  • permissions: the list of permissions that has been granted or revoked
    • +
  • permissionBits: the permissions bit mask that is persisted with the authorization
    • +
  • type: the type of authorization, can be either 0 (GLOBAL), 1 (GRANT) or 2 (REVOKE)
    • +
  • resource: the name of the resource type
    • +
  • resourceId: The id of the resource. Can be '*' if granted or revoked for all instances of the resource type.
    • +
  • userId: The id of the user the authorization is bound to. Can be '*' if granted or revoked for all users. Is not present when groupId is set.
    • +
  • groupId: The id of the group the authorization is bound to. Is not present when userId is set.
    • +
+
UpdateAdmin +
    +
  • permissions: the list of permissions that has been granted or revoked
    • +
  • permissionBits: the permissions bit mask that is persisted with the authorization
    • +
  • type: the type of authorization, can be either 0 (GLOBAL), 1 (GRANT) or 2 (REVOKE)
    • +
  • resource: the name of the resource type
    • +
  • resourceId: The id of the resource. Can be '*' if granted or revoked for all instances of the resource type.
    • +
  • userId: The id of the user the authorization is bound to. Can be '*' if granted or revoked for all users. Is not present when groupId is set.
    • +
  • groupId: The id of the group the authorization is bound to. Is not present when userId is set.
    • +
+
DeleteAdmin +
    +
  • permissions: the list of permissions that has been granted or revoked
    • +
  • permissionBits: the permissions bit mask that is persisted with the authorization
    • +
  • type: the type of authorization, can be either 0 (GLOBAL), 1 (GRANT) or 2 (REVOKE)
    • +
  • resource: the name of the resource type
    • +
  • resourceId: The id of the resource. Can be '*' if granted or revoked for all instances of the resource type.
    • +
  • userId: The id of the user the authorization is bound to. Can be '*' if granted or revoked for all users. Is not present when groupId is set.
    • +
  • groupId: The id of the group the authorization is bound to. Is not present when userId is set.
    • +
+
PropertyCreateAdmin +
    +
  • name: the name of the property that was created
    • +
+
UpdateAdmin +
    +
  • name: the name of the property that was updated
    • +
+
DeleteAdmin +
    +
  • name: the name of the property that was deleted
    • +
+
+ + +[op-log-set-annotation-instance-mod]: {{< ref "/user-guide/process-engine/process-instance-modification.md#annotation" >}} \ No newline at end of file diff --git a/content/user-guide/process-engine/process-instance-modification.md b/content/user-guide/process-engine/process-instance-modification.md index a3fb32135..9a87f5b55 100644 --- a/content/user-guide/process-engine/process-instance-modification.md +++ b/content/user-guide/process-engine/process-instance-modification.md @@ -617,7 +617,7 @@ runtimeService.createProcessInstanceModification(processInstanceId) .annotation("Modified to resolve an error.") .execute(); ``` -It will be visible in [User Operation Log]({{< ref "/user-guide/process-engine/history.md#annotation-of-user-operation-logs" >}}) for the performed modification. +It will be visible in [User Operation Log]({{< ref "/user-guide/process-engine/history/user-operation-log.md#annotation-of-user-operation-logs" >}}) for the performed modification. ## Soundness Checks diff --git a/content/user-guide/quarkus-integration/configuration.md b/content/user-guide/quarkus-integration/configuration.md index b3a2b93a5..515bbd6f2 100644 --- a/content/user-guide/quarkus-integration/configuration.md +++ b/content/user-guide/quarkus-integration/configuration.md @@ -83,7 +83,7 @@ A `QuarkusProcessEngineConfiguration` instance provides the following defaults: Camunda Cockpit works best with history level - }}">FULL. + }}">FULL. full diff --git a/content/user-guide/spring-boot-integration/configuration.md b/content/user-guide/spring-boot-integration/configuration.md index e986cf652..f250ece70 100644 --- a/content/user-guide/spring-boot-integration/configuration.md +++ b/content/user-guide/spring-boot-integration/configuration.md @@ -79,7 +79,7 @@ public PlatformTransactionManager camundaTransactionManager(@Qualifier("camundaB ### `DefaultHistoryConfiguration` -Applies the history configuration to the process engine. If not configured, the history level [FULL]({{< ref "/user-guide/process-engine/history.md#choose-a-history-level" >}}) is used. +Applies the history configuration to the process engine. If not configured, the history level [FULL]({{< ref "/user-guide/process-engine/history/history-configuration.md#choose-a-history-level" >}}) is used. If you want to use a custom `HistoryEventHandler`, you just have to provide a bean implementing the interface. ```java diff --git a/content/webapps/admin/auditing.md b/content/webapps/admin/auditing.md index 9e84f059c..47acb4fee 100644 --- a/content/webapps/admin/auditing.md +++ b/content/webapps/admin/auditing.md @@ -13,7 +13,7 @@ menu: Please note that this feature is only included in the enterprise edition of Camunda 7, it is not available in the community edition. {{< /enterprise >}} -It is often desired to inspect which user performed which operation for auditing purposes. Admin operations are logged in the [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) that is part of the process engine's history. The log allows to understand +It is often desired to inspect which user performed which operation for auditing purposes. Admin operations are logged in the [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) that is part of the process engine's history. The log allows to understand * which operation was performed * which user performed an operation @@ -21,7 +21,7 @@ It is often desired to inspect which user performed which operation for auditing * which entities (process instances, tasks, etc.) were involved * which changes were made -Please see the [complete table]({{< ref "/user-guide/process-engine/history.md#accessing-the-user-operation-log" >}}) of APIs that produce User Operation Logs. +Please see the [complete table]({{< ref "/user-guide/process-engine/history/user-operation-log.md#accessing-the-user-operation-log" >}}) of APIs that produce User Operation Logs. # Operation Log in Admin {{< img src="../img/admin-system-audit.png" title="Operation Log" >}} diff --git a/content/webapps/cockpit/_index.md b/content/webapps/cockpit/_index.md index e71823b36..cab53e7c8 100644 --- a/content/webapps/cockpit/_index.md +++ b/content/webapps/cockpit/_index.md @@ -25,4 +25,4 @@ A big part of Cockpit's functionality relies on historical data, and some of thi Therefore, to gain the full feature set of Cockpit, and not suffer any UX degradation due to unavailable data, [History Level][history-levels] `FULL` should be set. [cockpit-plugins]: {{< ref "/webapps/cockpit/extend/plugins.md" >}} -[history-levels]: {{< ref "/user-guide/process-engine/history.md#choose-a-history-level" >}} +[history-levels]: {{< ref "/user-guide/process-engine/history/history-configuration.md#choose-a-history-level" >}} diff --git a/content/webapps/cockpit/auditing.md b/content/webapps/cockpit/auditing.md index fbde34e47..0a95bb025 100644 --- a/content/webapps/cockpit/auditing.md +++ b/content/webapps/cockpit/auditing.md @@ -15,7 +15,7 @@ menu: Please note that this feature is only included in the enterprise edition of Camunda 7, it is not available in the community edition. {{< /enterprise >}} -Since Cockpit is a very powerful tool, it is often desired to inspect which user performed which operation for auditing purposes. Cockpit operations that change state are logged in Camunda 7's [user operation log]({{< ref "/user-guide/process-engine/history.md#user-operation-log" >}}) that is part of the process engine history. The log allows to understand +Since Cockpit is a very powerful tool, it is often desired to inspect which user performed which operation for auditing purposes. Cockpit operations that change state are logged in Camunda 7's [user operation log]({{< ref "/user-guide/process-engine/history/user-operation-log.md" >}}) that is part of the process engine history. The log allows to understand * which user performed an operation * which operation was performed @@ -23,7 +23,7 @@ Since Cockpit is a very powerful tool, it is often desired to inspect which user * which entities (process instances, tasks, etc.) were involved * which changes were made -To get a more detailed explanation about the Java and REST API methods to get user operations, check out [this url]({{< ref "/user-guide/process-engine/history.md#accessing-the-user-operation-log" >}}). +To get a more detailed explanation about the Java and REST API methods to get user operations, check out [this url]({{< ref "/user-guide/process-engine/history/user-operation-log.md#accessing-the-user-operation-log" >}}). # Operation Log in Cockpit {{< img src="../img/cockpit-operation-log.png" title="Operation Log" >}} diff --git a/content/webapps/cockpit/batch/monitoring.md b/content/webapps/cockpit/batch/monitoring.md index 8e31d1aec..2c0e74dcc 100644 --- a/content/webapps/cockpit/batch/monitoring.md +++ b/content/webapps/cockpit/batch/monitoring.md @@ -40,7 +40,7 @@ You can combine multiple search pills to narrow down the search results. ## Completed -Below the currently running batches, completed batches along with their start- and end-time are displayed. Completed batches are only visible when the process engine [history level]({{< ref "/user-guide/process-engine/history.md#choose-a-history-level">}}) is set to FULL. +Below the currently running batches, completed batches along with their start- and end-time are displayed. Completed batches are only visible when the process engine [history level]({{< ref "/user-guide/process-engine/history/history-configuration.md#choose-a-history-level">}}) is set to FULL. # Batch Details