Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>This page outlines the history support that is anticipated to be part of Activiti 5.0.</p>
<table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=Note" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9Tm90ZX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>This page currently describes a proposal for the history support only and does not reflect the current state of the implementation in Activiti.</p></td></tr></table>

<h1>Purpose</h1>

<p>The history module provides access to historic process execution data and acts as a data provider for basic process execution reports and statistics. In an initial version, the history module should just provide enough information to feed simple statistical reports and queries about process instance / activity instance executions and their executon times.</p>

<h2>Semantics: History vs. Audit</h2>

<p>While history is focussing on the fact that and when a specific process or activity has been executed and how long it took to execute it, audit aims for providing comprehensive information on what exactly has been done during a process execution. Typically, the data provided by history builds the base for creating reports and statistics while audit aims for satisfying the regulatory/legal requirements of providing traceability and information on who changed what and from what value to what new value. Due to this different requirements, the natural data model for history and audit differ fundamentally: a history data model contains a consolidated view on executed process steps, optimized for querying, an audit data model in contrast focus on persisting the actual events together with the context data (user, condition evaluations, process data, ...) needed to trace the change.</p>

<p>Scope of the initial history support is limited to reporting/statistics, not audit. Based on the current process event bus infrastructure, an audit component could be built without any dependency or relation to the history support.</p>

<h1>Reports</h1>

<p>The following reports should be included in Activiti 5.0:</p>
<ul>
	<li># of process instances created within a time range, grouped by process definitions</li>
	<li>minimal, maximal, and average execution process instance execution time, grouped by process definitions</li>
	<li>minimal, maximal, and average execution time for activity instances for a specific process definition</li>
</ul>

<p>Reports are provided by a specific report service, that in turn uses the history mechanism for accessing basic historic data.</p>

<p>These reports should be made available as a chart within Activity Probe or Explorer (TBD).</p>

<h1>Data Model</h1>

<p>The history data model consists of two main relations:</p>

<p>HistoricProcessInstance</p>
<ul>
	<li>processInstanceId</li>
	<li>processDefinitionId</li>
	<li>startTime</li>
	<li>endTime</li>
	<li><em>duration</em></li>
</ul>

<p>HistoricActivityInstance</p>
<ul>
	<li>activityInstanceId</li>
	<li>activityId</li>
	<li><em>activityName</em></li>
	<li><em>activityType</em></li>
	<li>processInstanceId</li>
	<li><em>processDefinitionId</em></li>
	<li>startTime</li>
	<li>endTime</li>
	<li><em>duration</em></li>
</ul>

<p>Italic attributes are there for providing a denormalized data view optimized for querying from external tools, directly based on the history data tables (e.g. activities can be grouped by processDefinitionId without the need for performing a join on the historic process instance table). As a consequence, the two relations are not linked in any way (i.e. no foreign key from historic activity instances to historic process instances). The same attributes and structure are reflected in the entities.</p>

<p>The history data model is built and maintained by specific event consumers that listen to process instances started/ended and activity instance started/ended event propagated by the process event bus.</p>

<h1>Service</h1>

<p>A historic data service will provide access to historic data in a read-only way. The history data service is configured globally per process engine and is accessible via the process engine configuration.</p>

<h1>Query API</h1>

<p>The query API allows for describing and executing queries against historic process and activity instances. The query API is designed in a &quot;fluent&quot; way, similar to the query APIs for tasks or jobs. Access to the query object is provided through the history data service. The query API is not intended to superseed direct access to the historic data tables, but provides access to historic data in a convenient way for programmatic queries.</p>

<p>The query API supports the following features:</p>
<ul>
	<li>restrictions: by processInstanceId, processDefinitionId, activityId, activityType (combinations of restrictions possible, depending on historic data type), date ranges (start / end)</li>
	<li>sorting: by startDate, processInstanceId (single sorting only)</li>
	<li>grouping: by processDefinitionId</li>
</ul>