[jboss-svn-commits] JBL Code SVN: r19070 - labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Mar 18 18:26:20 EDT 2008
Author: irooskov at redhat.com
Date: 2008-03-18 18:26:20 -0400 (Tue, 18 Mar 2008)
New Revision: 19070
Modified:
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml
Log:
Continued fixing written files
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml 2008-03-18 22:19:02 UTC (rev 19069)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml 2008-03-18 22:26:20 UTC (rev 19070)
@@ -131,35 +131,33 @@
</para>
</important>
<para>There are a few persistence managers, some are database specific
- (eg Oracle). There is a SimpleDBPersistenceManager which works with any
- database that supports JDBC - you also specify the database type, so it
+ (eg Oracle). Also of interest is a SimpleDBPersistenceManager which works with any
+ database that supports JDBC, specify the database type so it
uses the specific DDL to create the table structure (all major databases
are supported).</para>
<para>The BRMS will create the tables the first time it is started up if
- it is running against a fresh (empty) RDBMS - so its important to note
- that the user credentials supplied have permissions to create tables (at
- least initially, on first run, after that they could be locked
+ it is running against a fresh (empty) RDBMS. In order to acomplish this, the user credentials supplied are granted permission to create tables (at
+ least on the first run, after there is the ability to be locked
down).</para>
</section>
<section>
<title>Searching and indexing, Version storage</title>
- <para>Jackrabbit has a separate storage area for version storage (as
+ <para>Jackrabbit has a separate area for version storage (as
over time, the number of old versions will increase, yet it should not
slow down the performance of the main data store). The version storage
- also has its own persistence manage configuration in the repository.xml,
- but for most purposes you can use the same database as the main storage
- (just with a different schema object prefix - ie in your database, all
+ also has its own persistence management configuration in the repository.xml,
+ but for most purposes the same database as the main storage can be used
+ (just with a different schema object prefix, for instance in the database, all
the version data will be prefixed with "version_" but otherwise in the
same tablespace). See the repository.xml for more details of
this.</para>
<para>Lucene is used to provide indexing across the semi structured
data, and across versions. This indexing is generally best stored on a
- filesystem, local to the BRMS (as per the default in the repository.xml)
- - in most cases the default is fine.</para>
+ filesystem, local to the BRMS (as per the default in the repository.xml); in most cases the default is fine.</para>
</section>
</section>
@@ -167,62 +165,57 @@
<title>Security</title>
<para>Please note that giving someone access to the BRMS indicates a level of trust.
- Being able to editing and build rules is providing a great deal of power to a user. Thus you should not open up the BRMS to your entire organisation - but instead to a select few. Use https (http with TLS/SSL) whereever possible (even internally in a companies network this is a good idea). Use this power wisely - this not a "run of the mill" application that provides read/write access to a database, but something much more power. Just imagine you are spider man - with great power comes great responsibility (of course even more so for super man).</para>
+ Being able to edit and build rules is providing a great deal of power to a user. The BRMS should not be open to an entire organisation, but instead to a select few. Use https (http with TLS/SSL) whereever possible (even internally in a companies network this is a good idea). This not a regular application that provides read/write access to a database, but something much more powerful.</para>
<para>Security is configured by using the components.xml file in the war
- file. To customize this, you will need to unzip the war file, and locate
- the components.xml file which is in the WEB-INF directory.</para>
+ file. To customize this, the war file will need to be unzipped, and
+ the <filename>components.xml</filename> file located, which is in the WEB-INF directory.</para>
- <para>The JAAS standard is used as the underlying authentication and
- authorization mechanism, the upshot of which means its very flexable and
- able to integrate into most existing environments.</para>
+ <para>The Java Authentication and Authorization Service (JAAS) standard is used as the underlying authentication and
+ authorization mechanism, which means flexability and
+ the ability to integrate into most existing environments.</para>
<para>Out of the box, the BRMS shows a login screen, but no security
- credentials are enforced - the user name is used, but no password check is
- performed. To enforce authentication, you need to configure it to use an
- appropriate user directory (you may have Active Directory or similar
- already).</para>
+ credentials are enforced; the user name is used, but no password check is
+ performed. To enforce authentication, configuration needs to be undertaken to use an
+ appropriate user directory.</para>
- <para>In the components.xml file, you should located a security
- configuration section like the following:</para>
+ <para>In the <filename>components.xml</filename> file, a security configuration section should be located, like the following:</para>
- <programlisting><!-- SECURITY CONFIGURATION -->
+ <screen><!-- SECURITY CONFIGURATION -->
<!-- default (will take any username, useful if you want to keep track of users but not authenticate -->
<security:identity authenticate-method="#{defaultAuthenticator.authenticate}"/>
<!-- NO authentication. This will bypass the login screen when you hit the app. Everyone is "guest" -->
-<!-- <security:identity authenticate-method="#{nilAuthenticator.authenticate}"/> --> </programlisting>
+<!-- <security:identity authenticate-method="#{nilAuthenticator.authenticate}"/> --> </screen>
- <para>As you can see from above, the 2 "out of the box" options are pass
- through - which means any user is allowed in, or bypassed, in which case
- there is no login screen (eg you may be securing access to the app via a
- web server anyway).</para>
+ <para>The 2 default options are passed
+ through (or bypassed), meaning any user is allowed in. If access is bypassed then there will be no login screen. This may be done because access is being secured to the application through a
+ web server).</para>
<section>
- <title>Using your containers security and LDAP</title>
+ <title>Using containers security and the Lightweight Directory Access Protocol (LDAP)</title>
<para>Every application server supports advanced configurations which
can work with your existing security infrastructure. The case of JBoss
AS will be shown here as an example.</para>
- <programlisting><security:identity authenticate-method="#{authenticator.authenticate}"
- jaas-config-name="other"/></programlisting>
+ <screen><security:identity authenticate-method="#{authenticator.authenticate}"
+ jaas-config-name="other"/></screen>
- <para>This will use the "other" jaas config in JBoss AS. If you look in
- [jboss install dir]/server/default/conf you will see a login-config.xml
- file. This file contains various configs. If you use "other" like the
- one above, then it will look for users.properties and roles.properties
+ <para>This will use the <emphasis>other</emphasis> jaas config in JBoss AS. In
+ [jboss install dir]/server/default/conf there will be a <filename>login-config.xml</filename>
+ file. This file contains various configs. If the "other" option is being used as above, then it will look for users.properties and roles.properties
in the conf directory for usernames and passwords to authenticate
against (this is fine for a fixed small number of users).</para>
- <para>LDAP is perhaps the most popular choice for larger enterprises, so
- following is an example that works with Active Directory. You can get
- much more information on how to configure JBoss AS for all scenarios
- with LDAP from http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapLoginModule
- and http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapExtLoginModule.</para>
+ <para>LDAP is perhaps the most popular choice for larger enterprises.
+ The following is an example that works with Active Directory. More information on how to configure JBoss AS for all scenarios
+ with LDAP can be obtained from the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapLoginModule">LdapLiginModule</ulink> page
+ and the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=LdapExtLoginModule">LdapExtLoginModule</ulink> page.</para>
- <programlisting><application-policy name="brms">
+ <screen><application-policy name="brms">
<authentication>
<login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="required" >
<!--
@@ -247,18 +240,17 @@
<module-option name="searchScope">ONELEVEL_SCOPE</module-option>
</login-module>
</authentication>
-</application-policy></programlisting>
+</application-policy></screen>
- <para>To use the above, you would put jaas-config-name="brms" in the
- security:identity tag in the components.xml for the BRMS.</para>
+ <para>To use the above, place <code>jaas-config-name="brms"</code> in the
+ <property>security:identity</property> tag in the <filename>components.xml</filename> for the BRMS.</para>
<para>Similar configuration examples can be found for other directory
services.</para>
- <para>LDAP isn't the final word, you can use JDBC against a database of
- user name, or you can write your own login module to use any sort of
- weird and wonderful authentication and authorization systems that you
- may have to deal with (that would be an extreme case, but its possible).
+ <para>LDAP isn't the final word, you can use Java DataBase Connectivity (JDBC) against a database of
+ user names, or a custom login module can be written to use any sort of
+ weird and wonderful authentication and authorization systems (that would be an extreme case, but its possible).
Refer to JBoss AS documentation (or documentation for your existing
application server).</para>
</section>
@@ -271,17 +263,15 @@
<title>Backups</title>
<para>How backups are performed is dependent on what persistence manager
- scheme you are using. Using the default one - then its a matter of
- backing up the repository directory (wherever you have it configured to
- be). Restoring it is simply a matter of copying across the repository
+ scheme is in use. If using the default, then it is a matter of
+ backing up the repository directory. Restoring it is simply a matter of copying across the repository
directory.</para>
- <para>Ideally you will either stop the BRMS application while a file
- backup is being done, or ensure that no one is using it.</para>
+ <para>Ideally the BRMS application will be stopped while a file
+ backup is being done, or it will not be in use.</para>
<para>In the case of using an external database (eg Oracle, MySQL), then
- the normal scheme can apply that you would use to backup those database
- (you do back them up, right?). In this case, when restoring, it is also
+ the normal scheme can apply for backing them up. In this case, when restoring, it is also
a good idea to clear the indexes (delete the directory where the indexes
are) so they are created fresh from the data (and thus guaranteed to be
in sync).</para>
@@ -290,33 +280,36 @@
<section>
<title>Asset list customization</title>
- <para>In a few places in the BRMS there is an asset list: this list can
- be customized by looking for the AssetListTable.properties file. You can
- then set the header names and the "getter" methods that are used to
- populate the columns. eg you could add in getCreator, or
- getExternalSource as extra fields if you were using them.</para>
+ <para>In a few places within the BRMS there is an asset list; this list can
+ be customized by looking for the <filename>AssetListTable.properties</filename> file. The header names and the "getter" methods that are used to
+ populate the columns can be set within this file. For example <methodname>getCreator</methodname> could be added, or
+ <methodname>getExternalSource</methodname> as extra fields if they are in use.</para>
</section>
<section>
<title>Customised selectors for package building</title>
- <para>When building packages (from the "Packages" feature) you have the option to specify the name of a "selector". This selector will filter the list of rules that are built into the package. What you enter in the selector text box, is the name of a selector as configured on the server.</para>
+ <para>When building packages (from the <emphasis>Packages</emphasis> feature) there is an option to specify the name of a <emphasis>selector</emphasis>. This selector will filter the list of rules that are built into the package. What is entered in the selector text box, is the name of a selector as configured on the server.</para>
<para>
- To configure a selector, you will need to "explode" the war file for the BRMS, and locate the selectors.properties file (note you can also put your own selectors.properties file in the system classpath if you like).
- In this file, you will find details on how you can configure a custom selector. The options are to use a drl file, or the name of a class that you have written (and which is available on the classpath). Classes must implement the AssetSelector interface. DRL files can also be used (there is an example one in the selectors.properties file). Each selector you configure has a unique name in this properties file - and this is the name that you can use when building packages.
+ To configure a selector, the war file will need to be unzipped for the BRMS, and locate the <filename>selectors.properties</filename> file.
+ In this file, you will find details on how you can configure a custom selector. The options are to use a drl file, or the name of a class that that has been written (and which is available on the classpath).</para>
+
+<para> Classes must implement the AssetSelector interface. DRL files can also be used (there is an example of this in the <filename>selectors.properties</filename> file). Each selector that is configured has a unique name in this properties file and this name is used can when building packages.
</para>
+ <note>
+ <para>
+ A custom selectors.properties file can be placed in the system classpath if desired.
+ </para>
+ </note>
+
</section>
<section>
- <title>Adding your own logos or styles to the BRMS web GUI</title>
+ <title>Adding logos or styles to the BRMS web Graphical User Interface (GUI)</title>
- <para>Everyone loves having their own logo on screen - this is to ensure
- that the people using the application don't forget who they work for or
- what product they are using for more then a nanosecond (the consequences
- of them forgetting are too terrible con contemplate).</para>
-
- <para>To achieve, this, you can "explode" the deployment war file, and
- locate the JBRMS.html file.</para> <programlisting>
+ <para>To achieve the addition of a custom logo, unzip the deployment war file, and
+ locate the <filename>JBRMS.html</filename> file.</para>
+<screen>
<html>
<head>
<meta name='gwt:module' content='org.drools.brms.JBRMS'>
@@ -331,39 +324,43 @@
<script language='javascript' src='gwt.js'></script>
<iframe id='__gwt_historyFrame' style='width:0;height:0;border:0'></iframe>
</body>
-</html></programlisting><para> The above is the contents of the JBRMS.html
- file - it is fairly empty (as most of the work is done by the GWT - the
- GUI is built dynamically in the browser). The parts you can customise
- are the style sheet - you can either edit the JBRMS.css (or better yet,
- take a copy, and change the style to be what you need), the "shortcut
- icon" (its what shows in the address bar in the browser etc - also
- change the "icon" link to be the same so it works in IE), and the header
+</html></screen>
+
+<para>
+ The <filename>JBRMS.html</filename>
+ file is fairly empty (as most of the work is done by the GWT - the
+ GUI is built dynamically in the browser). The parts that can be customised
+ are the style sheet by either editing the <filename>JBRMS.css</filename> or taking a copy and changing the style to what is required, including the <emphasis>shortcut
+ icon</emphasis> (this shows in the address bar in the browser), and the header
logo. The rest should be left as is, to allow the GWT components to be
loaded and attached to the page. This html page is loaded only once by
the browser when the user accesses the BRMS web GUI.</para>
-
- <para>The best way to customize is to take a copy of the JBRMS.html -
- and then edit. You can also change the URL by editing the web.xml via
- the normal means. </para>
+<important>
+ <para>
+ If changing the shortcut icon, be sure to change the <emphasis>icon</emphasis> link to be the same, so it works in Internet Explorer.
+ </para>
+</important>
+ <para>The URL can be edited inside the <filename>web.xml</filename> file.</para>
</section>
<section>
<title>Import and Export</title>
- <para>A JCR standard export/import feature is available from the Admin
+ <para>A Java Content Repository (JCR) standard import and export feature is available from the Admin
part of the web interface.</para>
<para>This will export the entire repository to an XML format as defined
by the JCR standard.</para>
- <para>In the case of import, it will clear any existing content in the
+ <para>In the case of importing, it will clear any existing content in the
database.</para>
- <para>This is not a substitute for backup but can be useful when
+ <para>This is not a substitute for backing up but can be useful when
migrating. It is important to note that version history is not exported
this way, only the current state. Hence it is still recommended that a
formal backup regime be used at all times on the repository database
itself.</para>
</section>
</section>
+
</section>
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml 2008-03-18 22:19:02 UTC (rev 19069)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml 2008-03-18 22:26:20 UTC (rev 19070)
@@ -7,9 +7,9 @@
<section>
<title>Quick start guide</title>
- <para>If you are reading this, you must be the impatient type who wants to kick the tyres (and light the fires) and have a look around as soon as possible. This section will provide a quick end to end tour of the steps involved (but does not go through the concepts in detail). This assumes you have installed the repository correctly, and are able to access the main login screen.</para>
+ <para>This section will provide a quick end to end tour of the steps involved in administrating the BRMS (but does not go through the concepts in detail). This assumes that the repository has been correctly installed and access to the main login screen is avaliable.</para>
- <para>You can also consult the wiki: http://wiki.jboss.org/wiki/Wiki.jsp?page=RulesRepository for some tutorials and user tips (it IS a wiki, so you can even contribute your own tips and examples and even upload files if you desire !).</para>
+ <para>The wiki can also be consulted: <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=RulesRepository">Drools wiki</ulink> for some tutorials and user tips. Since it is a wiki, contributions are encouraged.</para>
<figure>
<title>Main feature areas of BRMS</title>
@@ -37,7 +37,7 @@
</listitem>
<listitem>
- <para>Deployment: this is where deployment snapshots are managed.</para>
+ <para>Deployment: This is where deployment snapshots are managed.</para>
</listitem>
<listitem>
@@ -48,7 +48,7 @@
<section>
<title>Supported browser platforms</title>
- <para>The supported server side platforms are mentioned in the installation guide. For browsers - the major ones are supported, this includes Firefox (1.5 and up), IE6 and up, Opera, Safari etc. The preferred browser for most platforms is firefox, it is widely available and free, if you have any choice at all, Firefox is the preferred platform, followed by safari on mac.</para>
+ <para>The supported server side platforms are mentioned in the installation guide. The major browsers which are supported includes Firefox (1.5 and up), Internet Explorer (IE) 6 and up, Opera and Safari. The preferred browser for most platforms is Firefox which is widely available and free, followed by Safari on Macintosh.</para>
</section>
<section>
@@ -58,31 +58,30 @@
<itemizedlist>
<listitem>
- <para>Once deployed, go to "http://<your server>/drools-jbrms/" (This will show the initial info screen - or login screen depending on the configuration).</para>
+ <para>Once deployed, go to "http://<server>/drools-jbrms/" (This will show the initial info screen - or login screen depending on the configuration).</para>
</listitem>
<listitem>
- <para>If it is a brand new repository, you will want to go to "Admin", and choose "Manage Categories"</para>
-
- <para>(Add a few categories of your choosing, categories are only for classification, not for execution or anything else.)</para>
+ <para>If it is a brand new repository, go to <emphasis>Admin</emphasis>, and choose <emphasis>Manage Categories</emphasis>. Add categories for classification but note they are not for execution or anything besides classification.</para>
</listitem>
<listitem>
- <para>Rules need a fact model (object model) to work off, so next you will want to go to the Package management feature. From here you can click on the icon to create a new package (give it a meaningful name, with no spaces).</para>
+ <para> Since rules need a fact model (object model) to work off, the Package Management feature will be the next destination. From here, click on the icon to create a new package with a meaningful name and no spaces.</para>
</listitem>
<listitem>
- <para>To upload a model, use a jar which has the fact model (API) that you will be using in your rules and your code (go and make one now if you need to !). When you are in the model editor screen, you can upload a jar file, choose the package name from the list that you created in the previous step.</para>
+ <para>To upload a model, use a jar which has the fact model (API) that you will be using in the rules and code. When in the model editor screen, choose the package name from the list created in the previous step and upload the jar.</para>
</listitem>
<listitem>
- <para>Now edit your package configuration (you just created) to import the fact types you just uploaded (add import statements), and save the changes.</para>
+ <para>Configuration of the package can now be done to import the fact types just uploaded (add import statements), and save the changes.</para>
</listitem>
<listitem>
- <para>At this point, the package is configured and ready to go (you generally won't have to go through that step very often).</para>
-
- <para>(Note that you can also import an existing drl package - it will store the rules in the repository as individual assets).</para>
+ <para>At this point, the package is configured and ready to go (this will not have to be undertaken repeatedly.</para>
+ <note>
+ <para>An existing drl package can also be imported, storing the rules in the repository as individual assets.</para>
+ </note>
</listitem>
</itemizedlist>
</section>
@@ -100,35 +99,35 @@
</listitem>
<listitem>
- <para>You create a rule by clicking the icon with the rules logo (the head), and from that you enter a name.</para>
+ <para>Create a rule by clicking the icon with the rules logo (the head), and from that, enter a name.</para>
</listitem>
<listitem>
- <para>You will also have to choose one category. Categories provide a way of viewing rules that is separate to packages (and you can make rules appear in multiple packages) - think of it like tagging.</para>
+ <para>A category wil also ahve to be chosen. Categories provide a way of viewing rules that is separate to packages (as rules can appear in multiple packages).</para>
</listitem>
<listitem>
- <para>Chose the "Business rule (guided editor)" formats.</para>
+ <para>Chose the <emphasis>Business rule (guided editor)</emphasis> format.</para>
</listitem>
<listitem>
- <para>This will open a rule modeler, which is a guided editor. You can add and edit conditions and actions based on the model that is in use in the current package. Also, any DSL sentence templates setup for the package will be available.</para>
+ <para>This will open a rule modeler, which is a guided editor. Conditions and actions can be added and edited based on the model that is in use in the current package. Also, any DSL sentence templates setup for the package will be available.</para>
</listitem>
<listitem>
- <para>When you are done with rule editing, you can check in the changes (save), or you can validate or "view source" (for the effective source).</para>
+ <para>When the rule editing is complete, check in the changes (save), or validate or <emphasis>view source</emphasis> (for the effective source).</para>
</listitem>
<listitem>
- <para>You can also add/remove categories from the rule editor, and other attributes such as documentation (if you aren't sure what to do, write a document in natural language describing the rule, and check it in, that can also serve as a template later)</para>
+ <para>Categories can also be added or removed from the rule editor, and other attributes such as documentation (if unsure, write a document in natural language describing the rule, and check it in. This can also serve as a template later).</para>
</listitem>
</itemizedlist>
</section>
<section>
- <title>Finding stuff</title>
+ <title>Navigating the BRMS</title>
- <para>In terms of navigating, you can either use the Rules feature, which shows things grouped by categories, or you can use the Package feature, and view by package (and rule type). If you know the name or part of the name of an asset, you can also use the "Quick find", start typing a rule name and it will return a list of matches as you type (so if you have a sensible naming scheme, it will make it very quick to find stuff).</para>
+ <para>In terms of navigating, you can either use the Rules feature, which shows things grouped by categories, or use the Package feature, and view by package (and rule type). The <emphasis>Quick find</emphasis> method can also be used if the name or part of the name of an asset is known. Start typing a rule name and it will return a list of matches.</para>
</section>
<section>
@@ -136,15 +135,15 @@
<itemizedlist>
<listitem>
- <para>After you have edited some rules in a package, you can click on the package feature, open the package that you wish, and build the whole package.</para>
+ <para>After having edited some rules in a package, click on the package feature, open the package, and build the whole package.</para>
</listitem>
<listitem>
- <para>If that succeeds, then you will be able to download a binary package file which can be deployed into a runtime system.</para>
+ <para>Once that has succeeded a binary package file can be downloaded, which can be deployed into a runtime system.</para>
</listitem>
<listitem>
- <para>You can also take a "snapshot" of a package for deployment. This freezes the package at that point in time, so any concurrent changes to not effect the package. It also makes the package available on a URL of the form: "http://<your server>/drools-jbrms/org.drools.brms.JBRMS/packages/<packageName>/<snapshotName>" (where you can use that URL and downloads will be covered in the section on deployment).</para>
+ <para>a "snapshot" of a package can also be taken for deployment. This freezes the package at that point in time, so any concurrent changes do not effect the package. It also makes the package available on a URL of the form: <emphasis>http://<your server>/drools-jbrms/org.drools.brms.JBRMS/packages/<packageName>/<snapshotName></emphasis>.</para>
</listitem>
</itemizedlist>
</section>
@@ -156,7 +155,7 @@
<section>
<title>Rules are assets</title>
- <para>As the BRMS can manage many different types of rules (and more), they are all classed as "assets". An asset is anything that can be stored as a version in the repository. This includes decision tables, models, DSLs and more. Sometimes the word "rule" will be used to really mean "asset" (ie the things you can do also apply to the other asset types). You can think of asset as a lot like a file in a folder. Assets are grouped together for viewing, or to make a package for deployment etc.</para>
+ <para>As the BRMS can manage many different types of rules (and more), they are all classed as "assets". An asset is anything that can be stored as a version in the repository. This includes decision tables, models, DSLs and more. Sometimes the word "rule" will be used to really mean "asset" (ie the things that can be achieved also apply to other asset types). Think of assets as a file in a folder. Assets are grouped together for viewing, or to make a package for deployment (as examples).</para>
</section>
<section>
@@ -172,9 +171,9 @@
</mediaobject>
</figure>
- <para>Categories allow rules (assets) to be labeled (or tagged) with any number of categories that you define. This means that you can then view a list of rules that match a specific category. Rules can belong to any number of categories. In the above diagram, you can see this can in effect create a folder/explorer like view of assets. The names can be anything you want, and are defined by the BRMS administrator (you can also remove/add new categories - you can only remove them if they are not currently in use).</para>
+ <para>Categories allow rules (assets) to be labeled (or tagged) with any number of categories that are defined. This means that a list of rules can be viewed that match a specific category. Rules can belong to any number of categories. In the above diagram, it can be seen that this may in effect create a folder orexplorer view of assets. The names can be anything, and are defined by the BRMS administrator (categories can be added and removed; though a category can only be removed if it is not currently in use).</para>
- <para>Generally categories are created with meaningful name that match the area of the business the rule applies to (if the rule applies to multiple areas, multiple categories can be attached). Categories can also be used to "tag" rules as part of their life-cycle, for example to mark as "Draft" or "For Review".</para>
+ <para>Generally categories are created with meaningful names that match the area of the business the rule applies to (if the rule applies to multiple areas, multiple categories can be attached). Categories can also be used to <emphasis>tag</emphasis> rules as part of their life-cycle, for example to mark as <emphasis>Draft</emphasis> or <emphasis>For Review</emphasis>.</para>
<figure>
<title>Assets can have multiple categories</title>
@@ -186,11 +185,11 @@
</mediaobject>
</figure>
- <para>The view above shows the category editor/viewer that is seen when you open an asset. In this example you can see the asset belongs to 2 categories, with a "+" button to add additional items (use the trash can item to remove them). This means that when either category is used to show a list of assets, you will see that asset.</para>
+ <para>The view above shows the category editor/viewer that is seen when an asset is opened. In this example it can be seen that the asset belongs to 2 categories, with a "+" button to add additional items (use the trash can item to remove them). This means that when either category is used to show a list of assets, that asset will be seen.</para>
- <para>In the above example, the first Category "Finance" is a "top level" category. The second one: "HR/Awards/QAS" is a still a single category, but its a nested category: Categories are hierarchical. This means there is a category called "HR", which contains a category "Awards" (it will in fact have more sub-categories of course), and "Awards" has a sub-category of QAS. The screen shows this as "HR/Awards/QAS" - its very much like a folder structure you would have on your hard disk (the notable exception is of course that rules can appear in multiple places).</para>
+ <para>In the above example, the first Category <emphasis>Finance</emphasis> is a <emphasis>top level</emphasis> category. The second one: <emphasis>HR/Awards/QAS</emphasis> is a still a single category, but its a nested category: Categories are hierarchical. This means there is a category called <emphasis>HR</emphasis>, which contains a category <emphasis>Awards</emphasis> (it will in fact have more sub-categories), and <emphasis>Awards</emphasis> has a sub-category of <emphasis>QAS</emphasis>; the screen shows this as <emphasis>HR/Awards/QAS</emphasis>. It is similar to a folder structure that would be on a hard disk (the notable exception is that rules can appear in multiple places).</para>
- <para>When you open an asset to view or edit, it will show a list of categories that it currently belongs to If you make a change (remove or add a category) you will need to save the asset - this will create a new item in the version history. Changing the categories of a rule has no effect on its execution.</para>
+ <para>When an asset has been opened to view or edit, it will show a list of categories that it currently belongs to. If a change is made (remove or add a category), the asset will need to be saved. This creates a new item in the version history. Changing the categories of a rule has no effect on its execution.</para>
<figure>
<title>Creating categories</title>
@@ -202,16 +201,16 @@
</mediaobject>
</figure>
- <para>The above view shows the administration screen for setting up categories (there) are no categories in the system by default. As the categories can be hierarchical you chose the "parent" category that you want to create a sub-category for. From here categories can also be removed (but only if they are not in use by any current versions of assets).</para>
+ <para>The above view shows the administration screen for setting up categories; by default there are no categories in the system. As the categories can be hierarchical, chose the "parent" category that a sub-category is to be created for. From here categories can also be removed (but only if they are not in use by any current versions of assets).</para>
- <para>As a general rule, an asset should only belong to 1 or 2 categories at a time. Categories are critical in cases where you have large numbers of rules. The hierarchies do not need to be too deep, but should be able to see how this can help you break down rules/assets into manageable chunks. Its ok if its not clear at first, you are free to change categories as you go.</para>
+ <para>As a general rule, an asset should only belong to 1 or 2 categories at a time. Categories are critical in cases where there are large numbers of rules. The hierarchies do not need to be too deep, but should be able to assist in the break down of rules and assets into manageable chunks.</para>
</section>
<section>
- <title>The asset editor</title>
+ <title>The Asset Editor</title>
<figure>
- <title>The Asset editor view</title>
+ <title>The Asset Editor View</title>
<mediaobject>
<imageobject>
@@ -220,25 +219,25 @@
</mediaobject>
</figure>
- <para>The above diagram shows the "asset editor" with some annotated areas. The asset editor is where all rule changes are made. Below is a list which describes the different parts of the editor.</para>
+ <para>The above diagram shows the <emphasis>asset editor</emphasis> with some annotated areas. The asset editor is where all rule changes are made. Below is a list which describes the different parts of the editor.</para>
<itemizedlist>
<listitem>
<para>A</para>
- <para>This is where the "editor widget" lives - exactly what form the editor takes depends on the asset or rule type.</para>
+ <para>This is where the <emphasis>editor widget</emphasis> can be found. Exactly what form the editor takes depends on the asset or rule type.</para>
</listitem>
<listitem>
<para>B</para>
- <para>This is the documentation area - a free text area where descriptions of the rule can live. It is encouraged to write a plain description in the rule here before editing.</para>
+ <para>This is the documentation area. A free text area where descriptions of the rule can live. It is encouraged to write a plain description in the rule here before editing.</para>
</listitem>
<listitem>
<para>C</para>
- <para>These are the actions - for saving, archiving, changing status etc. Archiving is the equivalent of deleting an asset.</para>
+ <para>These are the actions. Example actions are saving, archiving and changing status. Archiving is the equivalent of deleting an asset.</para>
</listitem>
<listitem>
@@ -252,31 +251,31 @@
<para>This section contains read-only meta data, including when changes were made, and by whom.</para>
- <para>"Modified on:" - this is the last modified date.</para>
+ <para><emphasis>Modified on</emphasis>: This is the last modified date.</para>
- <para>"By:" - who made the last change.</para>
+ <para><emphasis>By</emphasis>: Who made the last change.</para>
- <para>"Note:" - this is the comment made when the asset was last updated (ie why a change was made)</para>
+ <para><emphasis>Note</emphasis>: This is the comment made when the asset was last updated (for instance, why a change was made).</para>
- <para>"Version:" - this is a number which is incremented by 1 each time a change is checked in (saved).</para>
+ <para><emphasis>Version</emphasis>: A number which is incremented by 1 each time a change is checked in (saved).</para>
- <para>"Created on:" - the date and time the asset was created.</para>
+ <para><emphasis>Created on</emphasis>: The date and time the asset was created.</para>
- <para>"Created by:" - this initial author of the asset.</para>
+ <para><emphasis>Created by</emphasis>: The initial author of the asset.</para>
- <para>"Format:" - the short format name of the type of asset.</para>
+ <para><emphasis>Format</emphasis>: The short format name of the type of asset.</para>
</listitem>
<listitem>
<para>F</para>
- <para>This shows what package the asset belong to (you can also change it from here).</para>
+ <para>This shows what package the asset belongs to (this can also be changed here).</para>
</listitem>
<listitem>
<para>G</para>
- <para>This is some more (optional) meta data (taken from the Dublin Core meta data standard)</para>
+ <para>This is extra (optional) meta data (taken from the Dublin Core meta data standard)</para>
</listitem>
<listitem>
@@ -295,12 +294,15 @@
<section>
<title>Business rules with the guided editor</title>
- <para>Guided editor style "Business rules": (also known as "BRL format"). These rules use the guided GUI which controls and prompts user input based on knowledge of the object model. This can also be augmented with DSL sentences.</para>
+ <para>Guided editor style <emphasis>Business rules</emphasis>: (also known as the <emphasis>BRL format</emphasis>). These rules use the guided GUI which controls and prompts for user input based on knowledge of the object model. This can also be augmented with DSL sentences.</para>
- <para>IMPORTANT: to use the BRL guided editor, someone will need to have you package configured before hand.</para>
+ <important>
+ <para>To use the BRL guided editor, the package must be configured.</para>
+
+ <para>
+ The details in this section are also applicaable to the guided editor in the Eclipse plug-in.</para>
+ </important>
- <para>Also note that there is a guided editor in the Eclipse plug in, most of the details in this section can also apply to it.</para>
-
<figure>
<title>The guided BRL editor</title>
@@ -311,13 +313,20 @@
</mediaobject>
</figure>
- <para>The above diagram shows the editor in action. The following description apply to the letter boxes in the diagram above:</para>
+ <para>The above diagram shows the editor in action. The following descriptions apply to the letter boxes in the diagram above:</para>
- <para>A: The different parts of a rule. The "WHEN" part is the condition, "THEN" action, and "(options)" are optional attributes that may effect the operation of the rule.</para>
+ <itemizedlist>
+ <listitem>
+ <para>A</para>
+
+ <para> The different parts of a rule. The <emphasis>WHEN</emphasis> part is the condition, <emphasis>THEN</emphasis> action, and <emphasis>(options)</emphasis> are optional attributes that may effect the operation of the rule.</para>
+ </listitem>
- <para>B: This shows a pattern which is declaring that the rule is looking for a "Driver" fact (the fields are listed below, in this case just "age"). Note the green triangle, it will popup a list of options to add to the fact declaration: you can add more fields (eg their "location"), or you can assign a variable name to the fact (which you can use later on if needs be). As well as adding more fields to this pattern - you can add "multiple field" constraints - ie constraints that span across fields (eg age > 42 or risk > 2). The popup dialog shows the options.</para>
+ <para>B</para>
+ <para>This shows a pattern which is declaring that the rule is looking for a <emphasis>Driver</emphasis> fact (the fields are listed below, in this case only <emphais>age</emphaiss> is shown). Note the green triangle, it will popup a list of options to add to the fact declaration. More fields can be added (for example, their <emphasis>location</emphasis>) and a variable name can be assigned to the fact(which ycan be used later). As well as adding more fields to this pattern, multiple field constraits can be added (for instance, age > 42 or risk > 2).</para>
- <para>C: The small "-" icons indicate you can remove something - in this case it would remove the whole Driver fact declaration. If its the one below, it would remove just the age constraint.</para>
+ <para>C</para>
+ <para>The small negation ("-") icons indicate something can be removed. In this case it would remove the whole Driver fact declaration. If its the one below, it would remove just the age constraint.</para>
<para>D: The "+" symbols allow you to add more patterns to the condition or the action part of the rule, or more attributes. In all cases, a popup option box is provided. For the "WHEN" part of the rule, you can choose to add a constraint on a fact (it will give you a list of facts), or you can use another conditional element, the choices which are : "There is no" - which means the fact+constraints must not exist, "There exists" - which means that there exists at least one match (but there only needs to be one - it will not trigger for each match), and "Any of" - which means that any of the patterns can match (you then add patterns to these higher level patterns). If you just put a fact (like is shown above) then all the patterns are combined together so they are all true ("and").</para>
@@ -326,7 +335,7 @@
<para>F: This shows an "action" of the rule, a rule consists of a list of actions. In this case, we are asserting/inserting a new fact, which is a rejection (with the "reason" field set to an explanation). There are quite a few other types of actions you can use: you can modify an existing fact (which tells the engine the fact has changed) - or you can simply set a field on a fact (in which case the engine doesn't know about the change - normally because you are setting a result). You can also retract a fact. In most cases the green arrow will give you a list of fields you can add so you can change the value. The values you enter are "literal" - in the sense that what you type is what the value is. If it needs to be a calculation, then add an "=" at the start of the value - this will be interpreted as a "formula" (for advanced users only) ! and the calculation will be performed (not unlike a spreadsheet).</para>
<para>G: This is where the rule options live. In this case, only salience is used which is a numeric value representing the rules "priority". This would probably be the most common option to use.</para>
-
+ </itemizedlist>
<section>
<title>User driven drop down lists</title>
More information about the jboss-svn-commits
mailing list