7.4. History Log

7.4.1. History Log

The history logs store information about the execution of process instances, so that the information can be retrieved and viewed at a later time. History logs contain information, for instance, about the number of processes that have run and are running.
This history log of execution information is created based on events that the process engine generates during execution. This is possible because the jBPM runtime engine provides a generic mechanism to listen to events. The necessary information can easily be extracted from these events and then persisted to a database. Filters can also be used to limit the scope of the logged information.

7.4.2. The Business Activity Monitoring Data Model

The jbpm-bam module contains an event listener that stores process-related information in a database using JPA or Hibernate directly. The data model itself contains three entities: one for process instance information, one for node instance information, and one for (process) variable instance information.
Process-related information within the database.

Figure 7.2. Business Activity Monitoring data model

The ProcessInstanceLog table contains the basic log information about a process instance.

Table 7.5. ProcessInstanceLog

Field Description Nullable
id The primary key and ID of the log entity NOT NULL
end_date When applicable, the end date of the process instance  
processid The name (ID) of the process  
processinstanceid The process instance ID NOT NULL
start_date The start date of the process instance  
The NodeInstanceLog table contains more information about which nodes were executed inside each process instance. Whenever a node instance is entered from one of its incoming connections or is exited through one of its outgoing connections, that information is stored in this table.

Table 7.6. NodeInstanceLog

Field Description Nullable
id The primary key and ID of the log entity NOT NULL
log_date The date of the event  
nodeid The node ID of the corresponding node in the process definition  
nodeinstanceid The node instance ID  
nodename The name of the node  
processid The ID of the process that the process instance is executing  
processinstanceid The process instance ID NOT NULL
type The type of the event (0 = enter, 1 = exit) NOT NULL
The VariableInstanceLog table contains information about changes in variable instances. The default is to only generate log entries after a variable changes. It is also possible to log entries before the variable's value changes.

Table 7.7. VariableInstanceLog

Field Description Nullable
id The primary key and ID of the log entity NOT NULL
log_date The date of the event  
processid The ID of the process that the process instance is executing  
processinstanceid The process instance ID NOT NULL
value The value of the variable at the time that the log is made  
variableid The variable ID in the process definition  
variableinstanceid The ID of the variable instance  

7.4.3. Storing Process Events in a Database

To log process history in a database, register the logger to the session: 
StatefulKnowledgeSession ksession = ...;
JPAWorkingMemoryDbLogger logger = new JPAWorkingMemoryDbLogger(ksession);

// invoke methods one your session here

logger.dispose();
Note that this logger is like any other audit logger, and one or more filters can be added by calling the method addFilter to ensure that only relevant information is stored in the database.
The Logger should be disposed of when it is no longer needed.
The persistence database is configured in the persistence.xml file, which is located business-central-server.war/WEB-INF/classes/META-INF/ directory of the JBoss BRMS 5.3 deployable installation. 
       <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
       <persistence
           version="1.0"
           xsi:schemaLocation=
           	"http://java.sun.com/xml/ns/persistence
           	 http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd
       		 http://java.sun.com/xml/ns/persistence/orm 
       		 http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
           xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="http://java.sun.com/xml/ns/persistence">

        <!--persistence-unit name="ProcessService">
         <jta-data-source>java:/DefaultDS</jta-data-source>
         <properties>
          <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
         </properties>
        </persistence-unit-->

         <persistence-unit name="org.jbpm.persistence.jpa" transaction-type="JTA">
           <provider>org.hibernate.ejb.HibernatePersistence</provider>
           <jta-data-source>java:/DefaultDS</jta-data-source>       
           <mapping-file>META-INF/JBPMorm.xml</mapping-file>
           <class>org.jbpm.persistence.processinstance.ProcessInstanceInfo</class>
           <class>org.drools.persistence.info.SessionInfo</class>
           <class>org.drools.persistence.info.WorkItemInfo</class>
           <class>org.jbpm.process.audit.ProcessInstanceLog</class>
           <class>org.jbpm.process.audit.NodeInstanceLog</class>
           <class>org.jbpm.process.audit.VariableInstanceLog</class>
           <properties>
             <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>          
             <property name="hibernate.max_fetch_depth" value="3"/>
             <property name="hibernate.hbm2ddl.auto" value="update" />
             <property name="hibernate.show_sql" value="false" />  
             <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.JBossTransactionManagerLookup" />
           </properties>        
         </persistence-unit>

       </persistence>