jBPM5 Core Engine API

To interact with the process engine(to for example start a process),you need to set up a session.
This session will be used to communicate with the process engine. A session needs to have a
reference to a knowledge base, which contains a reference to all the relevant process definitions.
This knowledge base is used to look up the process definitions whenever necessary. To create
a session, you first need to create a knowledge base, load all the necessary process definition
(this can be from various sources, like from classpath, file system or process repository) and then
instantiate a session.

When starting up your application, you first need to create a knowledge base that contains those process definitions.
You can then create a session based on this knowledge base so that, whenever a new sales
order then comes in, a new process instance is started for that sales order. That process instance
contains the state of the process for that specific sales request.
A knowledge base can be shared across sessions and usually is only created once, at the start of
the application (as creating a knowledge base can be rather heavy-weight as it involves parsing
and compiling the process definitions). Knowledge bases can be dynamically changed.
Sessions can be created based on a knowledge base and are used to execute processes and
interact with the engine. You can create as much independent session as you want and creating
a session is considered relatively lightweight. How many sessions you create is up to you. In
general, most simple cases start out with creating one session that is then called from various
places in your application.
If you don't know what to do, simply start by having one knowledge base that contains all your
process definitions and one create session that you then use to execute all your processes.

jBPM API:
The jBPM project has a clear separation between the API the users should be interacting with
and the actual implementation classes. The public API exposes most of the features we believe
"normal" users can safely use and should remain rather stable across releases.

1 To create a knowlegde base, use a knowledge builder to load processes from various resources
2 create a new knowledge base from that builder.

KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
kbuilder.add(ResourceFactory.newClassPathResource("MyFirstProcess.bpmn"), ResourceType.BPMN2);
KnowledgeBase kbase = kbuilder.newKnowledgeBase();

3Once you've loaded your knowledge base, you should create a session to interact with the engine.
4 create a session based on the earlier created knowledge base,and to start a process (by id).

5 Register listerners. A processEventListener can be used to listen to process-related events,like starting
or completing a process,entering and leaving a node,etc.
An event object provides access to related information, like the process instance and node
instance linked to the event. You can use this API to register your own event listeners.

public interface ProcessEventListener{

void beforeProcessStarted( ProcessStartedEvent event );
void afterProcessStarted( ProcessStartedEvent event );
void beforeProcessCompleted( ProcessCompletedEvent event );
void afterProcessCompleted( ProcessCompletedEvent event );
void beforeNodeTriggered( ProcessNodeTriggeredEvent event );
void afterNodeTriggered( ProcessNodeTriggeredEvent event );
void beforeNodeLeft( ProcessNodeLeftEvent event );
void afterNodeLeft( ProcessNodeLeftEvent event );
void beforeVariableChanged(ProcessVariableChangedEvent event);
void afterVariableChanged(ProcessVariableChangedEvent event);

}

jBPM out-of-the-box provides a listener that can be used to create an audit log (either to the
console or the a file on the file system). This audit log contains all the different events that occurred
at runtime so it's easy to figure out what happened.