<?xml version="1.0" encoding="UTF-8"?>
<chapter id="ch.process-repository"
         version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
  <title>Process Repository</title>

  <para>A process repository is an important part of your BPM architecture if you start using more and more business processes in your applications and especially if you want to have the ability to dynamically update them. The process repository is the location where you store and manage your business processes. Because they are not deployed as part of your application, they have their own life cycle, meaning you can update your business processes dynamically, without having to change the application code.</para>

  <para>Note that a process repository is a lot more than simply a database to store your process definitions. It almost acts as a combination of a source code management system, content management system, collaboration suite and development and testing environment. These are the kind of features you can expect from a process repository:</para>

  <itemizedlist>
    <listitem>Persistent storage of your processes so the latest version can always easily be accessed from anywhere, including versioning</listitem>
    <listitem>Build and deploy selected processes</listitem>
    <listitem>User-friendly (web-based) interface to manage, update and deploy your processes (targeted to business users, not just developers)</listitem>
    <listitem>Authentication / authorization to make sure only people that have the right role can see and/or edit your processes</listitem>
    <listitem>Categorization and searching</listitem>
    <listitem>Scenario testing to make sure you don't break anything when you change your process</listitem>
    <listitem>Collaboration and other social features like comments, notifications on change, etc.</listitem>
    <listitem>Synchronization with your development environment</listitem>
  </itemizedlist>

  <para>Actually, it would be better to talk about a knowledge repository, as the repository will not only store your process definitions, but possibly also other related artefacts like task forms, your domain model, associated business rules, etc. Luckily, we don't have to reinvent the wheel for this, as the Guvnor project acts as a generic knowledge repository to store any type of artefacts and already supports most of these features.</para>

  <para>The following screencast shows how you can upload your process definition to Guvnor, along with the process form (that is used when you try to start a new instance of that process to collect the necessary data), task forms (for the human tasks inside the process), and the process image (that can be annotated to show runtime progress). The jBPM-console is configured to get all this information from Guvnor whenever necessary and show them in the console.</para>

    <figure>
      <ulink url="http://people.redhat.com/kverlaen/jBPM5-guvnor-integration.swf">
        <mediaobject>
          <imageobject>
	    <imagedata align="center" fileref="images/Chapter-Guvnor/Screencast.png" format="PNG" role="" />
          </imageobject>
        </mediaobject>
      </ulink>
    </figure>

  <para>If you use the installer, that should automatically download and install the latest version of Guvnor as well. So simply deploy your assets (for example using the Guvnor Eclipse integration as shown in the screencast, also automatically installed) to Guvnor (taking some naming conventions into account, as explained below), build the package and start up the console.</para>

  <para>The current integration of jBPM-console with Guvnor uses the following conventions to find the artefacts it needs:</para>

  <itemizedlist>
    <listitem>jBPM-console looks up artefacts from all available Guvnor packages (it does not look for assets in the Global Area). You can
    alternatively modify the guvnor.packages property in jBPM.console.properties to limit the lookup to only the packages you need, for example:
    guvnor.packages=defaultPackage, myPackageA, myPackageB</listitem>
    <listitem>A process should define the correct package name attribute, which needs to match the Guvnor package name it belongs to (otherwise you won't be able to build your package in Guvnor)</listitem>
    <listitem>Don't forget to build all of your packages in Guvnor before trying to view available processes in the console. Otherwise jBPM-console will not be able to retrieve the pkg from Guvnor.</listitem>
    <listitem>Currently, the console will load the process definitions the first time the list of processes is requested in the console. At this point, automatic updating from Guvnor when the package is rebuilt is turned off by default, so you will have to either configure this or restart the application server to get the latest versions.</listitem>
    <listitem>Task forms that should be associated with a specific process definition should have the name "{processDefinitionId}.ftl" or "{processDefinitionId}-taskform.ftl"</listitem>
    <listitem>Task forms for a specific human task should have the name "{taskName}.ftl" or "{taskName}-taskform.ftl"</listitem>
    <listitem>The process diagram for a specific process should have the name "{processDefinitionId}-image.png"</listitem>
    <listitem>By default jBPM-console looks up your Guvnor instance under http://localhost:8080/drools-guvnor. To change this, locate jbpm.console.properties and modify
    the guvnor.protocol, guvnor.host, and  guvnor.subdomain property values as needed</listitem>
    <listitem>jBPM-console communicates with Guvnor via its REST api. The default connect and read timeouts for this communication are set to 10 seconds via the guvnor.connect.timeout,
    and guvnor.read.timeout properties in jbpm.console.properties. You can edit values of these properties to set your specific timeout values (in milliseconds)</listitem>
    <listitem>If you are using Guvnor with JAAS authentication enabled, jBPM-console uses by default admin/admin credentials. To change this information again
    locate jbpm.console.properties and change the guvnor.usr, and guvnor.pwd property values.</listitem>
  </itemizedlist>

  <para>If you follow these rules, your processes, forms and images should show up without any issues in the jBPM-console.</para>

</chapter>
