<commit_before><?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
                    xmlns:xlink="http://www.w3.org/1999/xlink"
                    xmlns:xi="http://www.w3.org/2001/XInclude"
                    xmlns:svg="http://www.w3.org/2000/svg"
                    xmlns:m="http://www.w3.org/1998/Math/MathML"
                    xmlns:html="http://www.w3.org/1999/xhtml"
                    xmlns:db="http://docbook.org/ns/docbook" xml:base="./">

  <title>Console</title>

  <para>Drools processes can be managed through a web console.  This includes
  features like managing your process instances (starting/stopping/inspecting),
  inspecting your (human) task list and executing those tasks, and generating
  reports.</para>

  <para>The Drools build system generates two wars for you that can be deployed in your
  application server and contains the necessary libraries, the actual application,
  etc.  One jar contains the server application, the other one the client.  Download
  gwt-console-server-drools-{version}.war and gwt-console-drools-{version}.war and deploy
  them to your application server, {AS_HOME}/server/{configuration}/deploy (so for example,
  we are using jboss-4.2.3.GA/server/default/deploy).</para>

  <section>
    <title>Installation</title>

    <para>You need to have an application server installed.  This chapter assumes
    you are using the JBoss AS version 4.2.3.GA, but other versions or other
    application servers should be possible as well.</para>

    <section>
      <title>Installing Guvnor</title>

      <para>The process management console uses Drools Guvnor for loading the process
      definitions that can be used inside the console.  You therefore need to install
      Guvnor, to be able to add new process definitions to the repository, so they
      can then be managed through the console.  To do so, simply copy
      drools-guvnor.war to your application server,
      {AS_HOME}/server/{configuration}/deploy.</para>
      
    </section>

    <section>
      <title>Changing the persistence configuration of your runtime data</title>

      <para>The persistence.xml that is included in the server war refers to
      a JTA data source called "java:jdbc/testDS1" for storing the runtime information.
      To define this data source, create a testDS1-ds.xml file with the following content
      (note that we are using an embedded H2 in memory database, but similar configurations
      for another JPA data source is possible as well of course), and copy it to your
      application server deploy directory:</para>

      <programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;datasources&gt;
  &lt;local-tx-datasource&gt;
    &lt;jndi-name&gt;jdbc/testDS1&lt;/jndi-name&gt;
    &lt;connection-url&gt;jdbc:h2:mem:mydb&lt;/connection-url&gt;
    &lt;driver-class&gt;org.h2.jdbcx.JdbcDataSource&lt;/driver-class&gt;
    &lt;user-name&gt;sa&lt;/user-name&gt;
    &lt;password&gt;&lt;/password&gt;
  &lt;/local-tx-datasource&gt;
&lt;/datasources&gt;</programlisting>

      <para>Also make sure that the driver class can be found on the server classpath.
      In this case, we copied the h2-1.0.77.jar to the {AS_HOME}/server/{config}/lib
      folder.</para>

    </section>

    <section>
      <title>Changing the persistence configuration of your history data</title>

      <para>Drools uses Hibernate to persist history information in a database,
      for long term storagy.  The drools-bam module (inside the gwt-console-server-drools
      war) contains a hibernate.cfg.xml file that contains the default configuration,
      i.e using an embedded H2 in memory database.  However, this embedded database
      does not allow concurrent access.  If you are planning to use reporting, concurrent
      access might be required, so you should use the server configuration of the H2 in memory
      database in that case.  Change the connection url in the hibernate.cfg.xml
      to this:</para>

      <programlisting>
&lt;property name="connection.url"&gt;jdbc:h2:tcp://localhost/~/test&lt;/property&gt;</programlisting>

      <para>In this case, you should also make sure you have the H2 database running in
      server mode when running the application - for example by executing the org.h2.tools.Server
      class.</para>

    </section>

    <section>
      <title>Installing the reporting engine</title>

      <para>The reporting engine is based on the Eclipse BIRT engine.  You need to
      install the Eclipse BIRT runtime engine in your application server to be able to use
      the reporting functionality.  To do so, create a new directory called 
      {AS_HOME}/server/{configuration}/data/birt.  Download the Eclipse BIRT report
      engine version 2.3.2 (birt-runtime-2_3_2_2.zip), extract it and copy the ReportEngine
      directory to the newly created directory (the other directories are not needed).</para>

      <para>Next, you need to copy your process instance reports to the newly created
      directory as well.  Eclipse BIRT allows you to define your own reports based on
      existing data sources.  The console expects two different reports:
        <orderedlist>
          <listitem><emphasis>overall_activity.rptdesign</emphasis>: this reports shows
          an overview of all running process instances in your system</listitem>
          <listitem><emphasis>process_summary.rptdesign</emphasis>: this reports is
          shown when the user wants to look into one process definition.  It gives more
          details about all instances for that process.</listitem>
        </orderedlist>
      We have created some example reports you could use and customize according to your
      own requirements.  The example report templates can be found in the drools-bam
      module (src/test/resources).  Note that these example reports are also using the H2
      in memory database (in server mode).  If you configured the persistence of the history
      data differently, you will have to update the data source of these reports accordingly.
      You also need to copy your database drivers to the reporting plugin.  In our case,
      using H2, copy the h2-1.0.77.jar to {AS_HOME}/server/{configuration}/data/birt/ReportEngine/plugins/
      org.eclipse.birt.report.data.oda.jdbc_2.3.2.r232_v20090212/drivers.</para>

    </section>

    <section>
      <title>User authentication</title>

      <para>The application uses simple password authentication to verify who is allowed to
      use the application.  For example, usernames / passwords can be specified in a 
      users.properties file in {AS_HOME}/server/{configuration}/conf, for example:</para>

      <programlisting>
admin=admin
krisv=mypassword</programlisting>

      <para>The roles associated with these users can be specified in a roles.properties file
      in the same directory, for example:</para>

      <programlisting>
admin=admin,manager,user
krisv=admin,manager,user</programlisting>

    </section>

    <section>
      <title>Configure memory settings</title>

      <para>You might want to increase the memory that can be used by the application server
      (especially the PermGen space) if you run into OutOfMemory exceptions.  To do so, edit
      the run.conf or run.bat (depending on your OS) and for example add the following line:</para>

     <programlisting>
JAVA_OPTS="$JAVA_OPTS -XX:MaxPermSize=256m"</programlisting>

    </section>

    <para>You are now ready to startup the application server.  If you are using human tasks in
    your processes, you should also make sure you have the task service running (on 
    127.0.0.1:9123).  Also make sure your database is up and running of course.</para>

  </section>

  <section>
    <title>Adding process definitions in Guvnor</title>

    <para>Drools Guvnor allows you to manage all your business knowledge in a (logically)
    centralized location.   This includes all your process definitions, business rules, etc.
    The process management console automatically retrieves all the processes from the latest
    snapshot of the "default" package on Guvnor.  To find out how to get processes on the
    Guvnor repository (for example manually uploading them, or using the Eclipse Guvnor
    synchronization), check out the Guvnor documentation.  After deploying Guvnor to your
    application server, navigate to the following URL to open up Guvnor (replace the host 
    and/or port depending on how the application server is configured):
    <ulink url="http://localhost:8080/gwt-console">http://localhost:8080/gwt-console</ulink></para>

    <para>The following screenshot shows an example where the "default" package contains one<commit_msg> - fixed wrong link in docs<commit_after><?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
                    xmlns:xlink="http://www.w3.org/1999/xlink"
                    xmlns:xi="http://www.w3.org/2001/XInclude"
                    xmlns:svg="http://www.w3.org/2000/svg"
                    xmlns:m="http://www.w3.org/1998/Math/MathML"
                    xmlns:html="http://www.w3.org/1999/xhtml"
                    xmlns:db="http://docbook.org/ns/docbook" xml:base="./">

  <title>Console</title>

  <para>Drools processes can be managed through a web console.  This includes
  features like managing your process instances (starting/stopping/inspecting),
  inspecting your (human) task list and executing those tasks, and generating
  reports.</para>

  <para>The Drools build system generates two wars for you that can be deployed in your
  application server and contains the necessary libraries, the actual application,
  etc.  One jar contains the server application, the other one the client.  Download
  gwt-console-server-drools-{version}.war and gwt-console-drools-{version}.war and deploy
  them to your application server, {AS_HOME}/server/{configuration}/deploy (so for example,
  we are using jboss-4.2.3.GA/server/default/deploy).</para>

  <section>
    <title>Installation</title>

    <para>You need to have an application server installed.  This chapter assumes
    you are using the JBoss AS version 4.2.3.GA, but other versions or other
    application servers should be possible as well.</para>

    <section>
      <title>Installing Guvnor</title>

      <para>The process management console uses Drools Guvnor for loading the process
      definitions that can be used inside the console.  You therefore need to install
      Guvnor, to be able to add new process definitions to the repository, so they
      can then be managed through the console.  To do so, simply copy
      drools-guvnor.war to your application server,
      {AS_HOME}/server/{configuration}/deploy.</para>
      
    </section>

    <section>
      <title>Changing the persistence configuration of your runtime data</title>

      <para>The persistence.xml that is included in the server war refers to
      a JTA data source called "java:jdbc/testDS1" for storing the runtime information.
      To define this data source, create a testDS1-ds.xml file with the following content
      (note that we are using an embedded H2 in memory database, but similar configurations
      for another JPA data source is possible as well of course), and copy it to your
      application server deploy directory:</para>

      <programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;datasources&gt;
  &lt;local-tx-datasource&gt;
    &lt;jndi-name&gt;jdbc/testDS1&lt;/jndi-name&gt;
    &lt;connection-url&gt;jdbc:h2:mem:mydb&lt;/connection-url&gt;
    &lt;driver-class&gt;org.h2.jdbcx.JdbcDataSource&lt;/driver-class&gt;
    &lt;user-name&gt;sa&lt;/user-name&gt;
    &lt;password&gt;&lt;/password&gt;
  &lt;/local-tx-datasource&gt;
&lt;/datasources&gt;</programlisting>

      <para>Also make sure that the driver class can be found on the server classpath.
      In this case, we copied the h2-1.0.77.jar to the {AS_HOME}/server/{config}/lib
      folder.</para>

    </section>

    <section>
      <title>Changing the persistence configuration of your history data</title>

      <para>Drools uses Hibernate to persist history information in a database,
      for long term storagy.  The drools-bam module (inside the gwt-console-server-drools
      war) contains a hibernate.cfg.xml file that contains the default configuration,
      i.e using an embedded H2 in memory database.  However, this embedded database
      does not allow concurrent access.  If you are planning to use reporting, concurrent
      access might be required, so you should use the server configuration of the H2 in memory
      database in that case.  Change the connection url in the hibernate.cfg.xml
      to this:</para>

      <programlisting>
&lt;property name="connection.url"&gt;jdbc:h2:tcp://localhost/~/test&lt;/property&gt;</programlisting>

      <para>In this case, you should also make sure you have the H2 database running in
      server mode when running the application - for example by executing the org.h2.tools.Server
      class.</para>

    </section>

    <section>
      <title>Installing the reporting engine</title>

      <para>The reporting engine is based on the Eclipse BIRT engine.  You need to
      install the Eclipse BIRT runtime engine in your application server to be able to use
      the reporting functionality.  To do so, create a new directory called 
      {AS_HOME}/server/{configuration}/data/birt.  Download the Eclipse BIRT report
      engine version 2.3.2 (birt-runtime-2_3_2_2.zip), extract it and copy the ReportEngine
      directory to the newly created directory (the other directories are not needed).</para>

      <para>Next, you need to copy your process instance reports to the newly created
      directory as well.  Eclipse BIRT allows you to define your own reports based on
      existing data sources.  The console expects two different reports:
        <orderedlist>
          <listitem><emphasis>overall_activity.rptdesign</emphasis>: this reports shows
          an overview of all running process instances in your system</listitem>
          <listitem><emphasis>process_summary.rptdesign</emphasis>: this reports is
          shown when the user wants to look into one process definition.  It gives more
          details about all instances for that process.</listitem>
        </orderedlist>
      We have created some example reports you could use and customize according to your
      own requirements.  The example report templates can be found in the drools-bam
      module (src/test/resources).  Note that these example reports are also using the H2
      in memory database (in server mode).  If you configured the persistence of the history
      data differently, you will have to update the data source of these reports accordingly.
      You also need to copy your database drivers to the reporting plugin.  In our case,
      using H2, copy the h2-1.0.77.jar to {AS_HOME}/server/{configuration}/data/birt/ReportEngine/plugins/
      org.eclipse.birt.report.data.oda.jdbc_2.3.2.r232_v20090212/drivers.</para>

    </section>

    <section>
      <title>User authentication</title>

      <para>The application uses simple password authentication to verify who is allowed to
      use the application.  For example, usernames / passwords can be specified in a 
      users.properties file in {AS_HOME}/server/{configuration}/conf, for example:</para>

      <programlisting>
admin=admin
krisv=mypassword</programlisting>

      <para>The roles associated with these users can be specified in a roles.properties file
      in the same directory, for example:</para>

      <programlisting>
admin=admin,manager,user
krisv=admin,manager,user</programlisting>

    </section>

    <section>
      <title>Configure memory settings</title>

      <para>You might want to increase the memory that can be used by the application server
      (especially the PermGen space) if you run into OutOfMemory exceptions.  To do so, edit
      the run.conf or run.bat (depending on your OS) and for example add the following line:</para>

     <programlisting>
JAVA_OPTS="$JAVA_OPTS -XX:MaxPermSize=256m"</programlisting>

    </section>

    <para>You are now ready to startup the application server.  If you are using human tasks in
    your processes, you should also make sure you have the task service running (on 
    127.0.0.1:9123).  Also make sure your database is up and running of course.</para>

  </section>

  <section>
    <title>Adding process definitions in Guvnor</title>

    <para>Drools Guvnor allows you to manage all your business knowledge in a (logically)
    centralized location.   This includes all your process definitions, business rules, etc.
    The process management console automatically retrieves all the processes from the latest
    snapshot of the "default" package on Guvnor.  To find out how to get processes on the
    Guvnor repository (for example manually uploading them, or using the Eclipse Guvnor
    synchronization), check out the Guvnor documentation.  After deploying Guvnor to your
    application server, navigate to the following URL to open up Guvnor (replace the host 
    and/or port depending on how the application server is configured):
    <ulink url="http://localhost:8080/drools-guvnor">http://localhost:8080/drools-guvnor</ulink></para>

    <para>The following screenshot shows an example where the "default" package contains one
{'fraction_non_alphanumeric': 0.08170120701434753, 'fraction_numerical': 0.011842404919152812, 'mean_word_length': 3.337037037037037, 'pattern_counts': {'":': 0, '<': 179, '<?xml version=': 4, '>': 179, 'https://': 0, 'lorem ipsum': 0, 'www.': 10, 'xml': 28}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5111121', 'n_tokens_mistral': 4979, 'n_tokens_neox': 4677, 'n_words': 1898}