In many cases it is useful (if not necessary) to store information about the execution on process instances, so that this information can be used afterwards for example to verify what actions have been executed for a particular process instance, or to monitor and/or analyze the efficiency of a particular process, etc. Storing history information in the runtime database is usually not a good idea (as this would result in ever-growing runtime data, and monitoring and analysis queries might influence the performance of your runtime engine). That is why history information about the execution of process instances is stored separately.
This history log of execution information is created based on the events generated by the process engine during execution. The Drools runtime engine provides a generic mechanism to listen to different kinds of events. The necessary information can easily be extracted from these events and persisted, for example in a database. Filters can be used to only store the information you find relevant.
The drools-bam module contains an event listener that stores process-related information in a database (using hibernate). The database contains two tables, one for process instance information and one for node instance information (see figure below):
To log process history information in a database like this, you need to register the logger on your session (or working memory) like this:
StatefulKnowledgeSession session = ... new WorkingMemoryDbLogger(session);
Note that this logger is just a logger like any other audit logger. This means you can add one or more filters using the addFilter method to make sure that only relevant information is stored in the database. If you use more than one filter, only information that is accepted by all your filters will be persisted in the database.
To specify the database where the information should be stored, modify the hibernate.cfg.xml file. By default, it uses an in memory database (H2). Check out the hibernate documentation if you do not know how to do this.
All this information can easily be queried and can be used in a lot of different use cases, ranging from creating a history log for one specific process instance to analyzing the performance of all instances of a specific process. The org.drools.process.auditProcessInstanceDbLog class shows some examples on how to retrieve all process instances, one specific process instance (by id), all process instances for one specific process, all node instances of a specific process instance, etc. You can of course easily create your own hibernate queries or access the information in the database directly.