anchor.diff:  PoolingDataSourceWrapper pdsw = DataSourceFactory.setupPoolingDataSource("jdbc/jbpm-ds", driverProperties);
   ----
   
  -== Configuring the {PROCESS_ENGINE} to use persistence using `JBPMHelper` - for tests only
  -
  -
  -You need to configure the {PROCESS_ENGINE} to use persistence, usually simply by using the appropriate constructor when creating your session.
  -There are various ways to create a session (as we have tried to make this as easy as possible for you and have several utility classes for you, depending for example if you are trying to write a process JUnit test).
  -
  -The easiest way to do this is to use the `jbpm-test` module that allows you to easily create and test your processes.
  -The `JBPMHelper` class has a method to create a session, and uses a configuration file to configure this session, like whether you want to use persistence, the datasource to use, etc.
  -The helper class will then do all the setup and configuration for you.
  -
  -To configure persistence, create a [path]_jBPM.properties_
  - file and configure the following properties (note that the example below are the default properties, using an H2 in-memory database with persistence enabled, if you are fine with all of these properties, you don't need to add new properties file, as it will then use these properties by default):
  -
  -[source,properties]
  -----
  -
  -# for creating a datasource
  -persistence.datasource.name=jdbc/jbpm-ds
  -persistence.datasource.user=sa
  -persistence.datasource.password=
  -persistence.datasource.url=jdbc:h2:tcp://localhost/~/jbpm-db
  -persistence.datasource.driverClassName=org.h2.Driver
  -
  -# for configuring persistence of the session
  -persistence.enabled=true
  -persistence.persistenceunit.name=org.jbpm.persistence.jpa
  -persistence.persistenceunit.dialect=org.hibernate.dialect.H2Dialect
  -
  -# for configuring the human task service
  -taskservice.enabled=true
  -taskservice.datasource.name=org.jbpm.task
  -taskservice.usergroupcallback=org.jbpm.services.task.identity.JBossUserGroupCallbackImpl
  -taskservice.usergroupmapping=classpath:/usergroups.properties
  -----
  -
  -
  -If you want to use persistence, you must make sure that the datasource (that you specified in the [path]_jBPM.properties_
  - file) is initialized correctly.
  -This means that the database itself must be up and running, and the datasource should be registered using the correct name.
  -If you would like to use an H2 in-memory database (which is usually very easy to do some testing), you can use the `JBPMHelper` class to start up this database, using:
  -
  -[source,java]
  -----
  -
  -JBPMHelper.startH2Server();
  -----
  -
  -
  -To register the datasource (this is something you always need to do, even if you're not using H2 as your database, check below for more options on how to configure your datasource), use:
  -
  -[source,java]
  -----
  -
  -JBPMHelper.setupDataSource();
  -----
  -
  -
  -Next, you can use the `JBPMHelper` class to create your session (after creating your KIE base, which is identical to the case when you are not using persistence):
  -
  -[source,java]
  -----
  -
  -StatefulKnowledgeSession ksession = JBPMHelper.newStatefulKnowledgeSession(kbase);
  -----
  -
  -
  -Once you have done that, you can just call methods on this ksession (like ``startProcess``) and the {PROCESS_ENGINE} will persist all runtime state in the created datasource.
  -
  -You can also use the `JBPMHelper` class to recreate your session (by restoring its state from the database, by passing in the session id (that you can retrieve using ``ksession.getId()``)):
  -
  -[source,java]
  -----
  -
  -StatefulKnowledgeSession ksession = JBPMHelper.loadStatefulKnowledgeSession(kbase, sessionId);
  -----
  +== Configuring the {PROCESS_ENGINE} to use persistence
  +
  +
  +You need to configure the {PROCESS_ENGINE} to use persistence. The is most effectively done through `RuntimeEnvironmentBuilder`.
  +
  +It is easy to use `RuntimeEnvironmentBuilder` to create a session to run or test {PROCESS_ENGINE} flows. By default `RuntimeEnvironmentBuilder` searches for the `jdbc/jbpm-ds`, so this simple code segment creates a `KieSession` with an empty context.
  +
  +[source,java]
  +----
  +RuntimeEnvironmentBuilder builder = RuntimeEnvironmentBuilder.Factory.get()
  +        .newDefaultBuilder()
  +        .knowledgeBase(kbase);
  +RuntimeManager manager = RuntimeManagerFactory.Factory.get()
  +        .newSingletonRuntimeManager(builder.get(), "com.sample:example:1.0");
  +RuntimeEngine engine = manager.getRuntimeEngine(EmptyContext.get());
  +KieSession ksession = engine.getKieSession();
  +----
  +
  +The above code will also need a `kbase` parameter. One simple method is to use a `kmodule.xml` kjar descriptor found on the classpath as shown in this example. 
  +
  +[source,java]
  +----
  +KieServices ks = KieServices.Factory.get();
  +KieContainer kContainer = ks.getKieClasspathContainer();
  +KieBase kbase = kContainer.getKieBase("kbase");
  +----
  +
  +A `kmodule.xml` descriptor can include an attribute for resource packages to scan to find and deploy {PROCESS_ENGINE} workflows.
  +
  +[source,xml]
  +----
  +<kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule">
  +  <kbase name="kbase" packages="com.sample"/>
  +</kmodule>
  +----
  +
  +Control over the persistence can be accomplished through the `RuntimeEnvironmentBuilder::entityManagerFactory` method as shown below.
  +
  +
  +[source,java]
  +----
  +EntityManagerFactory emf = Persistence.createEntityManagerFactory("org.jbpm.persistence.jpa");                            
  +
  +RuntimeEnvironment runtimeEnv = RuntimeEnvironmentBuilder.Factory
  +        .get()
  +        .newDefaultBuilder()
  +        .entityManagerFactory(emf)
  +        .knowledgeBase(kbase)
  +        .get();
  +
  +StatefulKnowledgeSession ksession = (StatefulKnowledgeSession) RuntimeManagerFactory.Factory.get()
  +        .newSingletonRuntimeManager(runtimeEnv)
  +        .getRuntimeEngine(EmptyContext.get())
  +        .getKieSession();
  +----
  +
  +Once you have done that, you can just call methods on this ksession (like ``startProcess``) and the {PROCESS_ENGINE} will persist all runtime state in the created data source.
  +
  +You can re-create your session by using an identifier in the session ID (which you can retrieve using `ksession.getId()`) to restore the session state from the database:
  +
  +[source,java]
  +----
  +// recreate the session from database using the sessionId
  +StatefulKnowledgeSession ksession = JPAKnowledgeService.loadStatefulKnowledgeSession(sessionId, kbase, null, env );
  +----
  
positive.code: ----
  
  
  This configuration file refers to a data source called "jdbc/jbpm-ds". If you run your application in an application server (like for example JBoss AS), these containers typically allow you to easily set up data sources using some configuration (like for example dropping a datasource configuration file in the deploy directory).  Please refer to your application server documentation to know how to do this.
  
  For example, if you're deploying to JBoss Application Server v5.x, you can  create a datasource by dropping a configuration file in the deploy directory,  for example:
  
  [source,xml]
  ----
  
negative.code: If you're using the Eclipse IDE and the jBPM Eclipse plugin, you should make sure the necessary JARs are added to your jBPM runtime directory.
  You don't really need to do anything (as the necessary dependencies should already be there) if you are using the jBPM runtime that is configured by default when using the jBPM installer, or if you downloaded and unzipped the jBPM runtime artifact (from the downloads) and pointed the jBPM plugin to that directory.
  
  If you would like to manually add the necessary dependencies to your project, you need to put the [path]_jbpm-persistence-jpa.jar_ on your project's classpath as that contains the code for saving the runtime state whenever necessary.
  Depending on the persistence solution and database you are using, you may need additional dependencies.
  
  For the default combination of:
  