Hide Forgot
Affects: Documentation (Ref Guide, User Guide, etc.) Date of First Response: 2009-05-03 21:28:37 Append all comments on the document in this JIRA - review process is documented here: https://docspace.corp.redhat.com/clearspace/docs/DOC-17207
work in progress
Attachment: Added: BRMS_Userguide_WIP.pdf
We'll need to change/update the screenshots. The images in the book use the Drools logos and do not show the recent change to the navigation entry from "packages" to "knowledge base."
left some comments in a separate jira, strictly related to the 'logos and style' section - GUVNOR-291
Link: Added: This issue depends GUVNOR-291
Docs are/will be here: https://svn.devel.redhat.com/repos/jboss-soa/trunk/build-tools/docs/BRMS
Attachment: Removed: BRMS_Userguide_WIP.pdf
Attachment: Added: BRMS_Userguide.pdf
I updated the "branding content" but am a little confused by the reference to there being 2 guvnor.html files (GUVNOR-291). I cannot find "org.drools.guvnor.Guvnor/org.drools.guvnor.Guvnor" in the .war
Hey Darrin, org.drools.guvnor.Guvnor/org.drools.guvnor.Guvnor has been removed, see BRMS-106 for more details.
pdf checked in - note that this book is all entirely new content chapter 1 & 2 are highlighted as they have had significant work done on them. Chapter 3,4 & 5 have only been converted & had basic cleanup tasks performed. Chapter 5 may have many screenshots that are not up to date due to time constraints. If you find one that needs replacing can you please sample screenshot to replace it (preferably on Linux). Thanks.
Attachment: Added: DSL.jpg Attachment: Added: figure_4.5.jpg
Review comments: Cover page/title: Text: JBoss Enterprise BRMS Platform 5.0 Comment: Are we calling it a platform? -------------------------------- Page 1, Section 1.2. When to use a BRMS Text: 1. You need to manage versions/deployment of rules Comment: This might read better: You need to manage versioning/deployment of rules -------------------------------- Page 3, Section 2.1. Supported and recommended platforms Comment: This section should list Java 1.5 and 1.6 in the set of supported platforms. --------------------------------- Page 3, Section 2.2. Installation Text: 2. Extract Files The JBoss Enterprise BRMS Platform package contains two files, jboss-brms.war and jboss-brms-engine.zip. jboss-brms.war is a Java web archive containing the BRMS application. jboss-brms-engine.zip contains the jar files for the JBoss Rules 5 rules engine. These files are a subset of jboss-brms.war. Comment: The jboss-brms.CR2.zip file contains these (2) files: jboss-brms-engine.zip jboss-brms-manager.zip The jboss-brms-manager.zip file contains the jboss-brms.war file only. --------------------------------- Text: 3. "explode" the web archive Create a directory called jboss-brms.war and use a file archive tool to unpack the web archive into this directory. Comment: We should add this text as a warning: Be careful to name the directory "jboss-brms.war" - the ".war" is needed or the BRMS will not be properly deployed by the EAP server. --------------------------------- Page 5, Figure 2.2. BRMS first screen after login Comment: This screenshot shows an IP address of 10.64.5.95. I'm guessing that this is a system in Brisbane. It would be safer to use localhost if we have time to replace the screenshot. --------------------------------- Page 7, Procedure 2.2. Changing the repository location Text: 5. Move existing data store if required A new data store will be created by BRMS at the new location if there isn't one there already. If you wish to keep your existing data store then you can copy your existing files to the new location. Comment: Add this at the end of the above paragraph: "before you restart your server." --------------------------------- Page 8, Section 2.3.2. BRMS Database Configuration Text: The means by which the BRMS Platform manages access to these databases is handled by a Persistence Manager. There is a generic Persistence Manager for use with any JDBC compliant database as well as several specific to particular database implementations, such as Oracle or MySQL. Comment: We should remove the reference to MYSQL here as we do not yet support that DB. --------------------------------- Page 8, Section 2.3.2. BRMS Database Configuration Warning If you already have assets stored using the existing configuration that you wish to keep then you should export those before performing these steps. You can then import them into your new database afterwards. Comment: We should add a note to the warning that exporting and then importing a Rules repository is not supported as a backup and restore mechanism. Users should be told to set up a regular database backup procedure for their Worskpace and Versions databases. --------------------------------- Page 18, 2.6.1. Backups Comment: We should repeat the note from 2.3.2 - instructing the users to not depend on export/import as a backup mechanism. --------------------------------- Page 18, 2.6.2. Asset list customization Comment: This section refers to a AssetListTable.properties file. That file is not included in the .war: [ldimaggi@ldimaggi jboss-brms.war]$ pwd /jboss/local/EAP/jboss-eap-4.3/jboss-as/server/all/deploy/jboss-brms.war [ldimaggi@ldimaggi jboss-brms.war]$ ll total 56 -rw-rw-r-- 1 ldimaggi ldimaggi 3825 Apr 17 17:23 drools_logo.gif -rw-rw-r-- 1 ldimaggi ldimaggi 131 Apr 17 17:23 index.jsp drwxrwxr-x 3 ldimaggi ldimaggi 4096 Apr 17 19:57 META-INF -rw-rw-r-- 1 ldimaggi ldimaggi 130 Apr 17 17:23 NOTE.txt drwxrwxr-x 5 ldimaggi ldimaggi 4096 May 8 11:04 org.drools.guvnor.Guvnor drwxrwxr-x 2 ldimaggi ldimaggi 4096 Apr 17 19:57 org.drools.guvnor.Guvnor-aux drwxrwxr-x 4 ldimaggi ldimaggi 4096 May 12 13:41 WEB-INF [ldimaggi@ldimaggi jboss-brms.war]$ find . -name AssetListTable.properties -print --------------------------------- Page 18, 2.6.3. Customized selectors for package building Comment: Selectors should be marked as tech preview for this release. --------------------------------- Page 19, Section 2.6.4. Customizing the BRMS Platform User Interface Text: The most common branding change is to replace the images jbossrules_hdrbkg_blue.gif and drools.gif. Respectively these images are the logo at the top of the interface and the site "favorites icon" Comment: The jbossrules_hdrbkg_blue.gif is displayed multiple times on the top of the UI display. --------------------------------- Page 20, 2.6.5. Import and Export Text: This should not be used as a substitute for the backup system provided by your database vendor, but can be used migrating from one database to another. However the performance of this feature is extremely dependent on both the size of the database and the available memory on the server. Comment: We've seen failures on importing large repos. We may need to add some additional warnings to this section. Let's talk to Darrin about how to describe this. --------------------------------- Page 23, 4.1.1. Supported browsers Text: The current versions of the major web browsers are supported. This includes Firefox (version 1.5 and greater), Internet Explorer (version 7 and greater), Opera, Safari and Google Chrome. The preferred browser for most platforms is Firefox, it is widely available and free. Comment: We're certifying with these browsers: * Firefox 3 * Internet Explorer 7 * Safari 3 * The recommended minimum browser screen resolution is 1024 x 768 --------------------------------- Page 25, 4.1.4. Finding stuff Text: 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). Comment: How about changing the title to "Finding Assets" and replacing this text: '...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).' With: '...start typing a rule name and BRMS will return a list of matches as you type.' --------------------------------- Page 25, 4.2.1. Rules are assets Text: 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" (i.e. 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. Comment: Can we reword this to: As the BRMS can manage many different types of rules and other rules-related data, which are referred to as "assets". An asset is anything that can be stored as a version in the repository. This includes decision tables, models, DSLs and more. In this guide and in the UI, the word "rule" is sometimes used mean "asset" (i.e. the actions you can perform on rules can also be performed on the other asset types). Assets are grouped together for viewing, or to make a package for deployment. --------------------------------- Page 26, 4.2.2 Categorization Text: 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). Comment: The figure (Figure 4.2. Categories) no longer illustrates the finance, HR, etc. examples. It's been updated to the sample mortgage application. --------------------------------- Page 27, 4.2.2 Categorization Text: 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. Comment: Do we know why we are recommending that an asset only belong to 1-2 categories? Can we remove this line: '...Its OK if its not clear at first, you are free to change categories as you go...'? --------------------------------- Page 27, Figure 4.5. The Asset editor view Comment - see attached screenshot file - the UI has changed a bit since the image in figure 4-5 was created. --------------------------------- Page 27, last paragraph Text: These are the actions - for saving, archiving, changing status etc. Archiving is the equivalent of deleting an asset. Comment: We should also tell users that archived assets can be restored. --------------------------------- Page 28, 4.2.4.1. Business rules with the guided editor Text: IMPORTANT: to use the BRL guided editor, someone will need to have you package configured before hand. Comment: I think that this is trying to say: IMPORTANT: To use the BRL guided editor, your account must first have package access configured. --------------------------------- 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. --------------------------------- Page 29, 4.2.4.1. Business rules with the guided editor Text: 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. Comment: Replace its with it's. --------------------------------- Text: 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"). E: This shows the constraint for the "age" field. (Looking from left to right) the green triangle allows you to "assign" a variable name to the "age" field, which you may use later on in the rule. Next is the list of constraint operations - this list changes depending on the data type. After that is the value field - the value field will be one of: a) a literal value (e.g. number, text), b) a "formula" - in which case it is an expression which is calculated (this is for advanced users) or b) a variable (in which case a list will be provided to choose values from). After this there is a horizontal arrow icon, this is for "connective constraints" : these are constraints which allow you to have alternative values to check a field against, for example: "age is less than 42 or age is not equal to 39" is possibly this way. 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). Comment: These are large/dense blocks of text. It would be easier to read if the paragraphs were reformatted - perhaps into tables: 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) * "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"). E: This shows the constraint for the "age" field. (Looking from left to right) the green triangle allows you to "assign" a variable name to the "age" field, which you may use later on in the rule. Next is the list of constraint operations - this list changes depending on the data type. After that is the value field - the value field will be one of: * a literal value (e.g. number, text) * a "formula" - in which case it is an expression which is calculated (this is for advanced users) or b) a variable (in which case a list will be provided to choose values from). After this there is a horizontal arrow icon, this is for "connective constraints" : these are constraints which allow you to have alternative values to check a field against, for example: "age is less than 42 or age is not equal to 39" is possibly this way. 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). Comment: I think that we should remove the reference to "advanced users only" as we do not define or document what it means to be an advanced user in this guide. --------------------------------- Page 30, 4.2.4.1.2. Augmenting with DSL sentences Comment: If the package the rule is part of has a DSL configuration, when when you add conditions or actions, then it will provide a list of "DSL Sentences" which you can choose from - when you choose one, it will add a row to the rule - where the DSL specifies values come from a user, then a edit box (text) will be shown (so it ends up looking a bit like a form). This is optional, and there is another DSL editor. Text: See attached screensho "DSL.jpg" - is this the DSL editor the text refers to? --------------------------------- Page 31, 4.2.4.1.3. A more complex example: Text: In the above example, you can see it is using a mixture of literal values, and formulas. The second constraint on the "Person" fact, is a formula (in this case it is doing a silly calculation on the persons age, and checking something against their name - both "age" and "name" are fields of the Person fact in this case. In the 3rd line (which says "age is less than .." - it is also using a formula, although, in this case the formula does a calculation and returns a value (which is used in the comparison) - in the former case, it had to return True or False (in this case, its a value). Obvious formulas are basically pieces of code - so this is for experienced users only. Comment: Can we reword the last line to: "Formulas are pieces of executable code - so this is for experienced users only." --------------------------------- Page 31, Section 4.2.4.1.3. A more complex example: Text: Looking at the "Board" pattern (the second pattern with the horizontal grey bar): this uses a top level conditional element ("There is no") - this means that the pattern is actually looking for the "non existence" of a fact that matches the pattern. Note the "Any of:" - this means that EITHER the "type" field constraint is matched, or the "name" field is matched (to "myname" in the case above). This is what is termed a Multiple field constraint (you can nest these, and have it as complex as you like, depending on how much you want the next person to hate you: Some paraphrased advice: Write your rules in such as way as if the person who has to read/maintain them is a psychopath, has a gun, and knows where you live). Comment: We should remove this text: '...depending on how much you want the next person to hate you: Some paraphrased advice: Write your rules in such as way as if the person who has to read/maintain them is a psychopath, has a gun, and knows where you live)...' --------------------------------- Page 33, Section 4.2.4.3. Spreadsheet decision tables Text: To use a spreadsheet, you upload an xls (and can download the current version, as per the picture above). To create a new decision table, when you launch the rule wizard, you will get an option to create one (after that point, you can upload the xls file). Comment: We should also state that BRMS currently supports uploading from Microsoft Excel(tm) spreadsheets. --------------------------------- Page 34, Section 4.2.4.5. Technical rules (drl) Text: Technical (drl) rules are stored as text - they can be managed in the BRMS. A DRL can either be a whole chunk of rules, or an individual rule. if its an individual rule, no package statement or imports are required (in fact, you can skip the "rule" statement altogether, just use "when" and "then" to mark the condition and action sections respectively). Normally you would use the IDE to edit raw DRL files, since it has all the advanced tooling and content assistance and debugging, however there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you generally have a been for some "technical rules" - you can mix and match all the rule types together of course. Comment: Can we reword this as: Technical (drl) rules are stored as text and can be managed in the BRMS. A DRL can either be an individual rule or multiple rules. If it's an individual rule, no package statement or imports are required. You can skip the "rule" statement altogether and just use "when" and "then" to mark the condition and action sections respectively. Normally you would use an IDE to edit raw DRL files, since it has all the advanced tooling to support editing, content assistance and debugging. Also - we have to ask Michael what this means - how does a rule being "technical" require that it be edited in the BRMS? However there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you generally have a been for some "technical rules" - you can mix and match all the rule types together of course. --------------------------------- Page 35, 4.2.4.6. Functions Text: Functions are another asset type. They are NOT rules, and should only be used when necessary. The function editor is a textual editor. Functions Comment: The last line is truncated. --------------------------------- Page 35, Section 4.2.4.7. Data enumerations (drop down list configurations) Text: Data enumerations are an optional asset type that technical folk can configure to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to. Comment: Can we reword the paragraph to read: Data enumerations are an optional asset type that can be configured to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to. Comment: Can we mention a trade-marked product in our docs? I'm wondering about the Mini Mal surfboard: http://www.mcsurf.com.au/surfboards/mini_mal/72/1 --------------------------------- Page 36, 4.2.4.8. Advanced enumeration concepts Comment: The references to ULP and PULP types of fuel may be lost on readers who are not in Australia. Maybe we can add a footnote: http://www.fuelwatch.wa.gov.au/info/dsp_fuel_types.cfm Text: Lets imagine a simple fact model Comment: Replace Lets with "Let's" --------------------------------- Page 37, 4.2.4.8. Advanced enumeration concepts Text: Mode advanced enumerations: In the above cases, the values in the lists are calculated up front. This is fine for relatively static data, or small amounts of data. Imagine a scenario where you have lists of countries, each country has a list of states, each state has a list of localities, each locality has a list of streets and so on... You can see how this is a lot of data, and it can not be loaded up. The lists should be loaded dependent on what country was selected etc... Well the above can be addressed in the following fashion: Comment: We should remove the "..." and the "Well" --------------------------------- Page 37, 4.2.5. Templates of assets/rules Text: Tip: As you may have many similar rules, you can create rule templates, which are simply rules which are kept in an inactive package - you can then categories templates accordingly, and copy them as needed (choosing a live package as the target package). Comment: Can we convert this 'tip' into a note as defined in the orange box on page vii? --------------------------------- Page 38, 4.2.7. Package management Text: Configuring packages is generally something that is done once, and by someone with some experience with rules/models. Generally speaking, very few people will need to configure packages, and once they are setup, they can be copied over and over if needed. Package configuration is most definitely a technical task that requires the appropriate expertise. Comment: I will ask Michael Neale about this one - I would like for us to be able tell readers which type of user should perform this task. Comment: See: https://jira.jboss.org/jira/browse/BRMS-76 We should add this text to section 4.2.7: In BRMS, you have one Knowledge base, which contains one or more Knowledge Packages. In the UI, Knowledge Packages are also referred to as simply "packages." Text: So whilst rules (and assets in general) can appear in any number of categories, they only live in one package. If you think of the BRMS as a file system, then each package is a folder, and the assets live in that folder - as one big happy list of files. When you create a deployment snapshot of a package, you are effectively copying all the assets in that "folder" into another special "folder". Comment: Can we remove the reference to "one big happy list of files?" --------------------------------- Page 39, 4.2.7. Package management Text: One of the most critical things you need to do is configure packages. This is mostly importing the classes used by the rules, and globals variables. Comment: Should be reworded to: One of the most critical tasks you need to do is configuring packages. This task consists of importing the classes used by the rules, and defining global variables. Text: Finally you would "build" a package. Any errors caught are then shown at this point. If the build was successful, then you will have the option to create a snapshot for deployment. You can also view the "drl" that this package results in. WARNING: in cases of large numbers of rules, all these operations can take some time. Comment: After importing the package's classes and defining its global variables, you build the package. If the build is successful, then you will have the option to create a snapshot for deployment. You can also view the "drl" that is generated when the package is built. Comment: Can we convert the WARNING text into a warning? Text: It is optional at this stage to enter the name of a "selector" - see the admin section for details on how to configure custom selectors for your system (if you need them - selectors allow you to filter down what you build into a package - if you don't know what they are for, you probably don't need to use them). Comment: We should remove this text as selectors are tech preview in this BRMS release. --------------------------------- Page 41, 4.2.7.1. Importing drl packages Text: It is also possible to create a package by importing an existing "drl" file. When you choose to create a new package, you can choose an option to upload a .drl file. The BRMS will then attempt to understand that drl, break create a package for you. The rules in it will be stored as individual assets (but still as drl text content). Note that to actually build the package, you will need to upload an appropriate model (as a jar) to validate against, as a separate step. Comment: We should remove the word "break" in this paragraph. --------------------------------- Page 41, 4.2.8. Version management Text: Both assets and whole packages of assets are versioned in the BRMS, but the mechanism is slightly different. Individual assets are saved a bit like a version of a file in a source control system. However, packages of assets are versioned "on demand" by taking a snapshot (typically which is used for deployment). The next section talks about deployment management and snapshots. Comment: Can we remove the words "a bit?" Text: Each time you make a change to an asset, it creates a new item in the version history. This is a bit like having an unlimited undo. You can look back through the history of an individual asset like the list above, and view it (and restore it) from that point in time. Comment: Can we remove the words "a bit?" --------------------------------- Page 41, 4.2.9. Deployment management Comment: The first line ("Snapshots, URLS and binary packages:") should be removed. Text: Refer to the section on the Rule Agent for details on how you can use these URLs (and binary downloads) in your application, and how rules can be updated on the fly. Comment: The Rules Agent is described in section: 4.6.1. The Rule Agent --------------------------------- Page 43, 4.3. Creating a business user view Text: In most cases not all users will want to see all the functionality described here. You could have a subset of users who you only want to let view or edit certain sets of rules, without getting confused by all the other stuff. Comment: We should remove everything after the word "without." Text: In this case you can use fine grained authorization (see the Admin Guide on how to initialize this). By setting permissions on a per category basis, users that only have category permissions will see a limited subset of functionality, and only items that are tagged with those categories. Comment: There is no Admin Guide. We should refer users to section: 2.5. Security - Authorization --------------------------------- Page 46, 4.4. The fact model (object model) Text: Why would you chose declared types over jar files: generally this reinforces the fact that the model "belongs" to the rulebase, rather then the application, and allows the model to have a life-cycle separate from the application. It also removed the hassle of keeping jar files in sync between rules and the applications that use the rules. Comment: Can we reword this as: Some advantages to choosing declared types over jar files is that this reinforces the fact that the model "belongs" to the rulebase, rather than to the application, and allows the model to have a life-cycle separate from the application. It also removes the hassle of keeping jar files in sync between rules and the applications that use the rules. --------------------------------- Page 46, 4.5. The business user perspective Text: You can see from this manual, that some expertise and practice is required to use the BRMS Platform. In fact any software system in some sense requires that people be "technical" even if it has a nice looking GUI. Having said that, in the right hands the BRMS Platform can be setup to provide a suitable environment for non technical users. Comment: We should remove this paragraph. Text: The most appropriate rule formats for this use are using the Guided editor, Decision tables and DSL rules. You can use some DSL expressions also in the guided editor (so it provides "forms" for people to enter values). Comment: Reword to: For businesss users, the most appropriate rule formats for this use are using the Guided editor, Decision tables and DSL rules. You can use some DSL expressions also in the guided editor (so it provides "forms" for people to enter values). --------------------------------- Page 49, 4.6.3. Manual deployment Text: You can de-==serialize them and add them into any rulebase - essentially that is all you need to do. Comment: Reword to: You can de-serialize the objects and add them into any rulebase. --------------------------------- Page 50, 4.8. URLs Text: There are a few other URLs which are handy to know exist. The package deployment URL mentioned in the section about rule agent deployment also has a few other features: By appending .drl to the end of a URL, you will show the generated DRL for that package. e.g. /package/testPDSGetPackage/ LATEST.drl - will show the DRL (not the binary package) for the latest package. Further to this, you can append /assetName.drl - and it will show the generated DRL for that item. (even if it isn't a drl file). e.g. /package/testPDSGetPackage/LATEST/SomeFile.drl. Comment: This would read easier as bulleted list - can we reword this to: There are a few other URLs which are handy to know: * The package deployment URL mentioned in the section about rule agent deployment also has a few other features: By appending .drl to the end of a URL, you will show the generated DRL for that package. * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST.drl - Use this URL to download the source, or in the 'runtime agent' to access the rules in source form * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST - Use this url in the 'runtime agent' to fetch a pre compiled binary. * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST/SCENARIOS - Use this url to run the scenarios remotely and collect results. Further to this, you can append /assetName.drl - and it will show the generated DRL for that item. (even if it isn't a drl file). e.g. /package/testPDSGetPackage/LATEST/SomeFile.drl. --------------------------------- Page 51, 5.1. Source Code and Plug-in Details Text: The source code for the EGT is available at: http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/ drools-eclipse/ EGT consist of two plug-ins: org.guvnor.tools, org.eclipse.webdav and requires Eclipse 3.3.x. The Eclipse Drools plug-ins are also useful for viewing repository resources such as rule definitions, but not required for operation of the EGT. Comment: Replace "consist" with "consists." Comment: We need to tell the users that we are supporting JBDS 2 - not eclipse plus EGT plugins. --------------------------------- Page 53, Figure 5.4. Connection wizard Comment: The figure is wrong and should be replaced. We need to tell users that the default connection string supplied by JBDS will not work with BRMS. The string supplied by JBDS is: /drools-guvnor/org.drools.guvnor.Guvnor/webdav For BRMS, this needs to be: /jboss-brms/org.drools.guvnor.Guvnor/webdav The text in the paragraph following the figure is also wrong. (Same problem in - Figure 5.23. Preferences - on page 68) ---------------------------------
Assigning back to Darrin for edits
page 69, Appendix A. Example Persistence Manager configurations Here are several example Persistence Manager configurations for the supported databases. You will, of course, have to update the values in the configurations with those that are correct for your database, such as the JDBC URL and schemaObjectPrefix. Comment: We should state that for this release of the BRMS, Oracle is certified. The other DBs will be certified at a later date.
More info from Michael - thanks Michael! Yes - it would not be a sys admin but someone with specific rules expertise. Len DiMaggio wrote: > Hey Michael, > > Do we want the admins to configure the packages? Or maybe just users who have a better understanding of the customer's app? I vote for the second option - what do you think? > > > --Thanks, Len > > > > > > Page 38, 4.2.7. Package management > > Text: > > Configuring packages is generally something that is done once, and by someone with some > experience with rules/models. Generally speaking, very few people will need to configure packages, > and once they are setup, they can be copied over and over if needed. Package configuration is most > definitely a technical task that requires the appropriate expertise. > > Comment: > > I will ask Michael Neale about this one - I would like for us to be able tell readers which type of user should perform this task. >
THE HIGHER PRIORITY EDITS TO MAKE ARE: -------------------------------- Page 3, Section 2.1. Supported and recommended platforms Comment: This section should list Java 1.5 and 1.6 in the set of supported platforms. --------------------------------- Page 3, Section 2.2. Installation Text: 2. Extract Files The JBoss Enterprise BRMS Platform package contains two files, jboss-brms.war and jboss-brms-engine.zip. jboss-brms.war is a Java web archive containing the BRMS application. jboss-brms-engine.zip contains the jar files for the JBoss Rules 5 rules engine. These files are a subset of jboss-brms.war. Comment: The jboss-brms.CR2.zip file contains these (2) files: jboss-brms-engine.zip jboss-brms-manager.zip The jboss-brms-manager.zip file contains the jboss-brms.war file only. --------------------------------- Text: 3. "explode" the web archive Create a directory called jboss-brms.war and use a file archive tool to unpack the web archive into this directory. Comment: We should add this text as a warning: Be careful to name the directory "jboss-brms.war" - the ".war" is needed or the BRMS will not be properly deployed by the EAP server. --------------------------------- Page 5, Figure 2.2. BRMS first screen after login Comment: This screenshot shows an IP address of 10.64.5.95. I'm guessing that this is a system in Brisbane. It would be safer to use localhost if we have time to replace the screenshot. --------------------------------- Page 7, Procedure 2.2. Changing the repository location Text: 5. Move existing data store if required A new data store will be created by BRMS at the new location if there isn't one there already. If you wish to keep your existing data store then you can copy your existing files to the new location. Comment: Add this at the end of the above paragraph: "before you restart your server." --------------------------------- Page 8, Section 2.3.2. BRMS Database Configuration Text: The means by which the BRMS Platform manages access to these databases is handled by a Persistence Manager. There is a generic Persistence Manager for use with any JDBC compliant database as well as several specific to particular database implementations, such as Oracle or MySQL. Comment: We should remove the reference to MYSQL here as we do not yet support that DB. --------------------------------- Page 8, Section 2.3.2. BRMS Database Configuration Warning If you already have assets stored using the existing configuration that you wish to keep then you should export those before performing these steps. You can then import them into your new database afterwards. Comment: We should add a note to the warning that exporting and then importing a Rules repository is not supported as a backup and restore mechanism. Users should be told to set up a regular database backup procedure for their Worskpace and Versions databases. --------------------------------- Page 18, 2.6.1. Backups Comment: We should repeat the note from 2.3.2 - instructing the users to not depend on export/import as a backup mechanism. --------------------------------- Page 18, 2.6.2. Asset list customization Comment: This section refers to a AssetListTable.properties file. That file is not included in the .war: [ldimaggi@ldimaggi jboss-brms.war]$ pwd /jboss/local/EAP/jboss-eap-4.3/jboss-as/server/all/deploy/jboss-brms.war [ldimaggi@ldimaggi jboss-brms.war]$ ll total 56 -rw-rw-r-- 1 ldimaggi ldimaggi 3825 Apr 17 17:23 drools_logo.gif -rw-rw-r-- 1 ldimaggi ldimaggi 131 Apr 17 17:23 index.jsp drwxrwxr-x 3 ldimaggi ldimaggi 4096 Apr 17 19:57 META-INF -rw-rw-r-- 1 ldimaggi ldimaggi 130 Apr 17 17:23 NOTE.txt drwxrwxr-x 5 ldimaggi ldimaggi 4096 May 8 11:04 org.drools.guvnor.Guvnor drwxrwxr-x 2 ldimaggi ldimaggi 4096 Apr 17 19:57 org.drools.guvnor.Guvnor-aux drwxrwxr-x 4 ldimaggi ldimaggi 4096 May 12 13:41 WEB-INF [ldimaggi@ldimaggi jboss-brms.war]$ find . -name AssetListTable.properties -print --------------------------------- Page 18, 2.6.3. Customized selectors for package building Comment: Selectors should be marked as tech preview for this release. --------------------------------- Page 19, Section 2.6.4. Customizing the BRMS Platform User Interface Text: The most common branding change is to replace the images jbossrules_hdrbkg_blue.gif and drools.gif. Respectively these images are the logo at the top of the interface and the site "favorites icon" Comment: The jbossrules_hdrbkg_blue.gif is displayed multiple times on the top of the UI display. --------------------------------- Page 20, 2.6.5. Import and Export Text: This should not be used as a substitute for the backup system provided by your database vendor, but can be used migrating from one database to another. However the performance of this feature is extremely dependent on both the size of the database and the available memory on the server. Comment: We've seen failures on importing large repos. We may need to add some additional warnings to this section. Let's talk to Darrin about how to describe this. --------------------------------- Page 23, 4.1.1. Supported browsers Text: The current versions of the major web browsers are supported. This includes Firefox (version 1.5 and greater), Internet Explorer (version 7 and greater), Opera, Safari and Google Chrome. The preferred browser for most platforms is Firefox, it is widely available and free. Comment: We're certifying with these browsers: * Firefox 3 * Internet Explorer 7 * Safari 3 * The recommended minimum browser screen resolution is 1024 x 768 --------------------------------- Page 25, 4.1.4. Finding stuff Text: 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). Comment: How about changing the title to "Finding Assets" and replacing this text: '...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).' With: '...start typing a rule name and BRMS will return a list of matches as you type.' --------------------------------- Page 26, 4.2.2 Categorization Text: 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). Comment: The figure (Figure 4.2. Categories) no longer illustrates the finance, HR, etc. examples. It's been updated to the sample mortgage application. --------------------------------- Page 27, 4.2.2 Categorization Text: 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. Comment: Do we know why we are recommending that an asset only belong to 1-2 categories? Can we remove this line: '...Its OK if its not clear at first, you are free to change categories as you go...'? --------------------------------- Page 27, Figure 4.5. The Asset editor view Comment - see attached screenshot file - the UI has changed a bit since the image in figure 4-5 was created. --------------------------------- Page 27, last paragraph Text: These are the actions - for saving, archiving, changing status etc. Archiving is the equivalent of deleting an asset. Comment: We should also tell users that archived assets can be restored. --------------------------------- Page 28, 4.2.4.1. Business rules with the guided editor Text: IMPORTANT: to use the BRL guided editor, someone will need to have you package configured before hand. Comment: I think that this is trying to say: IMPORTANT: To use the BRL guided editor, your account must first have package access configured. --------------------------------- 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. --------------------------------- Page 29, 4.2.4.1. Business rules with the guided editor Text: 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. Comment: Replace its with it's. --------------------------------- Text: 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"). E: This shows the constraint for the "age" field. (Looking from left to right) the green triangle allows you to "assign" a variable name to the "age" field, which you may use later on in the rule. Next is the list of constraint operations - this list changes depending on the data type. After that is the value field - the value field will be one of: a) a literal value (e.g. number, text), b) a "formula" - in which case it is an expression which is calculated (this is for advanced users) or b) a variable (in which case a list will be provided to choose values from). After this there is a horizontal arrow icon, this is for "connective constraints" : these are constraints which allow you to have alternative values to check a field against, for example: "age is less than 42 or age is not equal to 39" is possibly this way. 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). Comment: These are large/dense blocks of text. It would be easier to read if the paragraphs were reformatted - perhaps into tables: 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) * "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"). E: This shows the constraint for the "age" field. (Looking from left to right) the green triangle allows you to "assign" a variable name to the "age" field, which you may use later on in the rule. Next is the list of constraint operations - this list changes depending on the data type. After that is the value field - the value field will be one of: * a literal value (e.g. number, text) * a "formula" - in which case it is an expression which is calculated (this is for advanced users) or b) a variable (in which case a list will be provided to choose values from). After this there is a horizontal arrow icon, this is for "connective constraints" : these are constraints which allow you to have alternative values to check a field against, for example: "age is less than 42 or age is not equal to 39" is possibly this way. 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). Comment: I think that we should remove the reference to "advanced users only" as we do not define or document what it means to be an advanced user in this guide. --------------------------------- Page 30, 4.2.4.1.2. Augmenting with DSL sentences Comment: If the package the rule is part of has a DSL configuration, when when you add conditions or actions, then it will provide a list of "DSL Sentences" which you can choose from - when you choose one, it will add a row to the rule - where the DSL specifies values come from a user, then a edit box (text) will be shown (so it ends up looking a bit like a form). This is optional, and there is another DSL editor. Text: See attached screenshot "DSL.jpg" - is this the DSL editor the text refers to? --------------------------------- Page 31, Section 4.2.4.1.3. A more complex example: Text: Looking at the "Board" pattern (the second pattern with the horizontal grey bar): this uses a top level conditional element ("There is no") - this means that the pattern is actually looking for the "non existence" of a fact that matches the pattern. Note the "Any of:" - this means that EITHER the "type" field constraint is matched, or the "name" field is matched (to "myname" in the case above). This is what is termed a Multiple field constraint (you can nest these, and have it as complex as you like, depending on how much you want the next person to hate you: Some paraphrased advice: Write your rules in such as way as if the person who has to read/maintain them is a psychopath, has a gun, and knows where you live). Comment: We should remove this text: '...depending on how much you want the next person to hate you: Some paraphrased advice: Write your rules in such as way as if the person who has to read/maintain them is a psychopath, has a gun, and knows where you live)...' --------------------------------- Page 33, Section 4.2.4.3. Spreadsheet decision tables Text: To use a spreadsheet, you upload an xls (and can download the current version, as per the picture above). To create a new decision table, when you launch the rule wizard, you will get an option to create one (after that point, you can upload the xls file). Comment: We should also state that BRMS currently supports uploading from Microsoft Excel(tm) spreadsheets. --------------------------------- Page 35, 4.2.4.6. Functions Text: Functions are another asset type. They are NOT rules, and should only be used when necessary. The function editor is a textual editor. Functions Comment: The last line is truncated. --------------------------------- Page 35, Section 4.2.4.7. Data enumerations (drop down list configurations) Can we mention a trade-marked product in our docs? I'm wondering about the Mini Mal surfboard: http://www.mcsurf.com.au/surfboards/mini_mal/72/1 --------------------------------- Page 36, 4.2.4.8. Advanced enumeration concepts Comment: The references to ULP and PULP types of fuel may be lost on readers who are not in Australia. Maybe we can add a footnote: http://www.fuelwatch.wa.gov.au/info/dsp_fuel_types.cfm Text: Lets imagine a simple fact model Comment: Replace Lets with "Let's" --------------------------------- Page 37, 4.2.5. Templates of assets/rules Text: Tip: As you may have many similar rules, you can create rule templates, which are simply rules which are kept in an inactive package - you can then categories templates accordingly, and copy them as needed (choosing a live package as the target package). Comment: Can we convert this 'tip' into a note as defined in the orange box on page vii? --------------------------------- Page 38, 4.2.7. Package management We should add this text to section 4.2.7: In BRMS, you have one Knowledge base, which contains one or more Knowledge Packages. In the UI, Knowledge Packages are also referred to as simply "packages." --------------------------------- Page 41, 4.2.7.1. Importing drl packages Text: It is also possible to create a package by importing an existing "drl" file. When you choose to create a new package, you can choose an option to upload a .drl file. The BRMS will then attempt to understand that drl, break create a package for you. The rules in it will be stored as individual assets (but still as drl text content). Note that to actually build the package, you will need to upload an appropriate model (as a jar) to validate against, as a separate step. Comment: We should remove the word "break" in this paragraph. --------------------------------- Page 43, 4.3. Creating a business user view Text: In most cases not all users will want to see all the functionality described here. You could have a subset of users who you only want to let view or edit certain sets of rules, without getting confused by all the other stuff. Comment: We should remove everything after the word "without." Text: In this case you can use fine grained authorization (see the Admin Guide on how to initialize this). By setting permissions on a per category basis, users that only have category permissions will see a limited subset of functionality, and only items that are tagged with those categories. Comment: There is no Admin Guide. We should refer users to section: 2.5. Security - Authorization --------------------------------- Page 46, 4.5. The business user perspective Text: You can see from this manual, that some expertise and practice is required to use the BRMS Platform. In fact any software system in some sense requires that people be "technical" even if it has a nice looking GUI. Having said that, in the right hands the BRMS Platform can be setup to provide a suitable environment for non technical users. Comment: We should remove this paragraph. Text: The most appropriate rule formats for this use are using the Guided editor, Decision tables and DSL rules. You can use some DSL expressions also in the guided editor (so it provides "forms" for people to enter values). Comment: Reword to: For businesss users, the most appropriate rule formats for this use are using the Guided editor, Decision tables and DSL rules. You can use some DSL expressions also in the guided editor (so it provides "forms" for people to enter values). --------------------------------- Page 49, 4.6.3. Manual deployment Text: You can de-==serialize them and add them into any rulebase - essentially that is all you need to do. Comment: Reword to: You can de-serialize the objects and add them into any rulebase. --------------------------------- Page 50, 4.8. URLs Text: There are a few other URLs which are handy to know exist. The package deployment URL mentioned in the section about rule agent deployment also has a few other features: By appending .drl to the end of a URL, you will show the generated DRL for that package. e.g. /package/testPDSGetPackage/ LATEST.drl - will show the DRL (not the binary package) for the latest package. Further to this, you can append /assetName.drl - and it will show the generated DRL for that item. (even if it isn't a drl file). e.g. /package/testPDSGetPackage/LATEST/SomeFile.drl. Comment: This would read easier as bulleted list - can we reword this to: There are a few other URLs which are handy to know: * The package deployment URL mentioned in the section about rule agent deployment also has a few other features: By appending .drl to the end of a URL, you will show the generated DRL for that package. * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST.drl - Use this URL to download the source, or in the 'runtime agent' to access the rules in source form * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST - Use this url in the 'runtime agent' to fetch a pre compiled binary. * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST/SCENARIOS - Use this url to run the scenarios remotely and collect results. Further to this, you can append /assetName.drl - and it will show the generated DRL for that item. (even if it isn't a drl file). e.g. /package/testPDSGetPackage/LATEST/SomeFile.drl. --------------------------------- Page 51, 5.1. Source Code and Plug-in Details Text: The source code for the EGT is available at: http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/ drools-eclipse/ EGT consist of two plug-ins: org.guvnor.tools, org.eclipse.webdav and requires Eclipse 3.3.x. The Eclipse Drools plug-ins are also useful for viewing repository resources such as rule definitions, but not required for operation of the EGT. Comment: Replace "consist" with "consists." Comment: We need to tell the users that we are supporting JBDS 2 - not eclipse plus EGT plugins. --------------------------------- Page 53, Figure 5.4. Connection wizard Comment: The figure is wrong and should be replaced. We need to tell users that the default connection string supplied by JBDS will not work with BRMS. The string supplied by JBDS is: /drools-guvnor/org.drools.guvnor.Guvnor/webdav For BRMS, this needs to be: /jboss-brms/org.drools.guvnor.Guvnor/webdav The text in the paragraph following the figure is also wrong. (Same problem in - Figure 5.23. Preferences - on page 68) --------------------------------- -------------------------------- Page 1, Section 1.2. When to use a BRMS Text: 1. You need to manage versions/deployment of rules Comment: This might read better: You need to manage versioning/deployment of rules -------------------------------- Page 3, Section 2.1. Supported and recommended platforms Comment: This section should list Java 1.5 and 1.6 in the set of supported platforms. --------------------------------- Page 3, Section 2.2. Installation Text: 2. Extract Files The JBoss Enterprise BRMS Platform package contains two files, jboss-brms.war and jboss-brms-engine.zip. jboss-brms.war is a Java web archive containing the BRMS application. jboss-brms-engine.zip contains the jar files for the JBoss Rules 5 rules engine. These files are a subset of jboss-brms.war. Comment: The jboss-brms.CR2.zip file contains these (2) files: jboss-brms-engine.zip jboss-brms-manager.zip The jboss-brms-manager.zip file contains the jboss-brms.war file only. --------------------------------- Text: 3. "explode" the web archive Create a directory called jboss-brms.war and use a file archive tool to unpack the web archive into this directory. Comment: We should add this text as a warning: Be careful to name the directory "jboss-brms.war" - the ".war" is needed or the BRMS will not be properly deployed by the EAP server. --------------------------------- Page 5, Figure 2.2. BRMS first screen after login Comment: This screenshot shows an IP address of 10.64.5.95. I'm guessing that this is a system in Brisbane. It would be safer to use localhost if we have time to replace the screenshot. --------------------------------- Page 7, Procedure 2.2. Changing the repository location Text: 5. Move existing data store if required A new data store will be created by BRMS at the new location if there isn't one there already. If you wish to keep your existing data store then you can copy your existing files to the new location. Comment: Add this at the end of the above paragraph: "before you restart your server." --------------------------------- Page 8, Section 2.3.2. BRMS Database Configuration Text: The means by which the BRMS Platform manages access to these databases is handled by a Persistence Manager. There is a generic Persistence Manager for use with any JDBC compliant database as well as several specific to particular database implementations, such as Oracle or MySQL. Comment: We should remove the reference to MYSQL here as we do not yet support that DB. --------------------------------- Page 8, Section 2.3.2. BRMS Database Configuration Warning If you already have assets stored using the existing configuration that you wish to keep then you should export those before performing these steps. You can then import them into your new database afterwards. Comment: We should add a note to the warning that exporting and then importing a Rules repository is not supported as a backup and restore mechanism. Users should be told to set up a regular database backup procedure for their Worskpace and Versions databases. --------------------------------- Page 18, 2.6.1. Backups Comment: We should repeat the note from 2.3.2 - instructing the users to not depend on export/import as a backup mechanism. --------------------------------- Page 18, 2.6.2. Asset list customization Comment: This section refers to a AssetListTable.properties file. That file is not included in the .war: [ldimaggi@ldimaggi jboss-brms.war]$ pwd /jboss/local/EAP/jboss-eap-4.3/jboss-as/server/all/deploy/jboss-brms.war [ldimaggi@ldimaggi jboss-brms.war]$ ll total 56 -rw-rw-r-- 1 ldimaggi ldimaggi 3825 Apr 17 17:23 drools_logo.gif -rw-rw-r-- 1 ldimaggi ldimaggi 131 Apr 17 17:23 index.jsp drwxrwxr-x 3 ldimaggi ldimaggi 4096 Apr 17 19:57 META-INF -rw-rw-r-- 1 ldimaggi ldimaggi 130 Apr 17 17:23 NOTE.txt drwxrwxr-x 5 ldimaggi ldimaggi 4096 May 8 11:04 org.drools.guvnor.Guvnor drwxrwxr-x 2 ldimaggi ldimaggi 4096 Apr 17 19:57 org.drools.guvnor.Guvnor-aux drwxrwxr-x 4 ldimaggi ldimaggi 4096 May 12 13:41 WEB-INF [ldimaggi@ldimaggi jboss-brms.war]$ find . -name AssetListTable.properties -print --------------------------------- Page 18, 2.6.3. Customized selectors for package building Comment: Selectors should be marked as tech preview for this release. --------------------------------- Page 20, 2.6.5. Import and Export Text: This should not be used as a substitute for the backup system provided by your database vendor, but can be used migrating from one database to another. However the performance of this feature is extremely dependent on both the size of the database and the available memory on the server. Comment: We've seen failures on importing large repos. We may need to add some additional warnings to this section. Let's talk to Darrin about how to describe this. --------------------------------- Page 23, 4.1.1. Supported browsers Text: The current versions of the major web browsers are supported. This includes Firefox (version 1.5 and greater), Internet Explorer (version 7 and greater), Opera, Safari and Google Chrome. The preferred browser for most platforms is Firefox, it is widely available and free. Comment: We're certifying with these browsers: * Firefox 3 * Internet Explorer 7 * Safari 3 * The recommended minimum browser screen resolution is 1024 x 768 --------------------------------- Page 25, 4.1.4. Finding stuff Text: 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). Comment: How about changing the title to "Finding Assets" and replacing this text: '...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).' With: '...start typing a rule name and BRMS will return a list of matches as you type.' --------------------------------- Page 26, 4.2.2 Categorization Text: 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). Comment: The figure (Figure 4.2. Categories) no longer illustrates the finance, HR, etc. examples. It's been updated to the sample mortgage application. --------------------------------- Page 27, 4.2.2 Categorization Text: 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. Comment: Do we know why we are recommending that an asset only belong to 1-2 categories? Can we remove this line: '...Its OK if its not clear at first, you are free to change categories as you go...'? --------------------------------- Page 27, Figure 4.5. The Asset editor view Comment - see attached screenshot file - the UI has changed a bit since the image in figure 4-5 was created. --------------------------------- Page 27, last paragraph Text: These are the actions - for saving, archiving, changing status etc. Archiving is the equivalent of deleting an asset. Comment: We should also tell users that archived assets can be restored. Page 31, Section 4.2.4.1.3. A more complex example: Text: Looking at the "Board" pattern (the second pattern with the horizontal grey bar): this uses a top level conditional element ("There is no") - this means that the pattern is actually looking for the "non existence" of a fact that matches the pattern. Note the "Any of:" - this means that EITHER the "type" field constraint is matched, or the "name" field is matched (to "myname" in the case above). This is what is termed a Multiple field constraint (you can nest these, and have it as complex as you like, depending on how much you want the next person to hate you: Some paraphrased advice: Write your rules in such as way as if the person who has to read/maintain them is a psychopath, has a gun, and knows where you live). Comment: We should remove this text: '...depending on how much you want the next person to hate you: Some paraphrased advice: Write your rules in such as way as if the person who has to read/maintain them is a psychopath, has a gun, and knows where you live)...' --------------------------------- Page 33, Section 4.2.4.3. Spreadsheet decision tables Text: To use a spreadsheet, you upload an xls (and can download the current version, as per the picture above). To create a new decision table, when you launch the rule wizard, you will get an option to create one (after that point, you can upload the xls file). Comment: We should also state that BRMS currently supports uploading from Microsoft Excel(tm) spreadsheets. --------------------------------- Page 35, 4.2.4.6. Functions Text: Functions are another asset type. They are NOT rules, and should only be used when necessary. The function editor is a textual editor. Functions Comment: The last line is truncated. --------------------------------- Page 35, Section 4.2.4.7. Data enumerations (drop down list configurations) Text: Data enumerations are an optional asset type that technical folk can configure to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to. Comment: Can we reword the paragraph to read: Data enumerations are an optional asset type that can be configured to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to. Comment: Can we mention a trade-marked product in our docs? I'm wondering about the Mini Mal surfboard: http://www.mcsurf.com.au/surfboards/mini_mal/72/1 --------------------------------- Page 36, 4.2.4.8. Advanced enumeration concepts Comment: The references to ULP and PULP types of fuel may be lost on readers who are not in Australia. Maybe we can add a footnote: http://www.fuelwatch.wa.gov.au/info/dsp_fuel_types.cfm Text: Lets imagine a simple fact model Comment: Replace Lets with "Let's" --------------------------------- Page 37, 4.2.4.8. Advanced enumeration concepts Text: Mode advanced enumerations: In the above cases, the values in the lists are calculated up front. This is fine for relatively static data, or small amounts of data. Imagine a scenario where you have lists of countries, each country has a list of states, each state has a list of localities, each locality has a list of streets and so on... You can see how this is a lot of data, and it can not be loaded up. The lists should be loaded dependent on what country was selected etc... Well the above can be addressed in the following fashion: Comment: We should remove the "..." and the "Well" --------------------------------- Page 38, 4.2.7. Package management Text: Configuring packages is generally something that is done once, and by someone with some experience with rules/models. Generally speaking, very few people will need to configure packages, and once they are setup, they can be copied over and over if needed. Package configuration is most definitely a technical task that requires the appropriate expertise. Comment: I will ask Michael Neale about this one - I would like for us to be able tell readers which type of user should perform this task. Comment: See: https://jira.jboss.org/jira/browse/BRMS-76 We should add this text to section 4.2.7: In BRMS, you have one Knowledge base, which contains one or more Knowledge Packages. In the UI, Knowledge Packages are also referred to as simply "packages." Text: So whilst rules (and assets in general) can appear in any number of categories, they only live in one package. If you think of the BRMS as a file system, then each package is a folder, and the assets live in that folder - as one big happy list of files. When you create a deployment snapshot of a package, you are effectively copying all the assets in that "folder" into another special "folder". Comment: Can we remove the reference to "one big happy list of files?" --------------------------------- Page 41, 4.2.7.1. Importing drl packages Text: It is also possible to create a package by importing an existing "drl" file. When you choose to create a new package, you can choose an option to upload a .drl file. The BRMS will then attempt to understand that drl, break create a package for you. The rules in it will be stored as individual assets (but still as drl text content). Note that to actually build the package, you will need to upload an appropriate model (as a jar) to validate against, as a separate step. Comment: We should remove the word "break" in this paragraph. --------------------------------- Page 41, 4.2.9. Deployment management Comment: The first line ("Snapshots, URLS and binary packages:") should be removed. Text: Refer to the section on the Rule Agent for details on how you can use these URLs (and binary downloads) in your application, and how rules can be updated on the fly. Comment: The Rules Agent is described in section: 4.6.1. The Rule Agent --------------------------------- Page 43, 4.3. Creating a business user view Text: In most cases not all users will want to see all the functionality described here. You could have a subset of users who you only want to let view or edit certain sets of rules, without getting confused by all the other stuff. Comment: We should remove everything after the word "without." Text: In this case you can use fine grained authorization (see the Admin Guide on how to initialize this). By setting permissions on a per category basis, users that only have category permissions will see a limited subset of functionality, and only items that are tagged with those categories. Comment: There is no Admin Guide. We should refer users to section: 2.5. Security - Authorization --------------------------------- Page 46, 4.5. The business user perspective Text: You can see from this manual, that some expertise and practice is required to use the BRMS Platform. In fact any software system in some sense requires that people be "technical" even if it has a nice looking GUI. Having said that, in the right hands the BRMS Platform can be setup to provide a suitable environment for non technical users. Comment: We should remove this paragraph. Text: The most appropriate rule formats for this use are using the Guided editor, Decision tables and DSL rules. You can use some DSL expressions also in the guided editor (so it provides "forms" for people to enter values). Comment: Reword to: For businesss users, the most appropriate rule formats for this use are using the Guided editor, Decision tables and DSL rules. You can use some DSL expressions also in the guided editor (so it provides "forms" for people to enter values). --------------------------------- Page 49, 4.6.3. Manual deployment Text: You can de-==serialize them and add them into any rulebase - essentially that is all you need to do. Comment: Reword to: You can de-serialize the objects and add them into any rulebase. --------------------------------- Page 50, 4.8. URLs Text: There are a few other URLs which are handy to know exist. The package deployment URL mentioned in the section about rule agent deployment also has a few other features: By appending .drl to the end of a URL, you will show the generated DRL for that package. e.g. /package/testPDSGetPackage/ LATEST.drl - will show the DRL (not the binary package) for the latest package. Further to this, you can append /assetName.drl - and it will show the generated DRL for that item. (even if it isn't a drl file). e.g. /package/testPDSGetPackage/LATEST/SomeFile.drl. Comment: This would read easier as bulleted list - can we reword this to: There are a few other URLs which are handy to know: * The package deployment URL mentioned in the section about rule agent deployment also has a few other features: By appending .drl to the end of a URL, you will show the generated DRL for that package. * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST.drl - Use this URL to download the source, or in the 'runtime agent' to access the rules in source form * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST - Use this url in the 'runtime agent' to fetch a pre compiled binary. * http://localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/package/mortgages/LATEST/SCENARIOS - Use this url to run the scenarios remotely and collect results. Further to this, you can append /assetName.drl - and it will show the generated DRL for that item. (even if it isn't a drl file). e.g. /package/testPDSGetPackage/LATEST/SomeFile.drl. --------------------------------- Page 51, 5.1. Source Code and Plug-in Details Text: The source code for the EGT is available at: http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/ drools-eclipse/ EGT consist of two plug-ins: org.guvnor.tools, org.eclipse.webdav and requires Eclipse 3.3.x. The Eclipse Drools plug-ins are also useful for viewing repository resources such as rule definitions, but not required for operation of the EGT. Comment: Replace "consist" with "consists." Comment: We need to tell the users that we are supporting JBDS 2 - not eclipse plus EGT plugins. --------------------------------- Page 53, Figure 5.4. Connection wizard Comment: The figure is wrong and should be replaced. We need to tell users that the default connection string supplied by JBDS will not work with BRMS. The string supplied by JBDS is: /drools-guvnor/org.drools.guvnor.Guvnor/webdav For BRMS, this needs to be: /jboss-brms/org.drools.guvnor.Guvnor/webdav The text in the paragraph following the figure is also wrong. (Same problem in - Figure 5.23. Preferences - on page 68) ---------------------------------
AND - THE LOWER PRIORITY EDITS TO MAKE ARE: -------------------------------- Page 1, Section 1.2. When to use a BRMS Text: 1. You need to manage versions/deployment of rules Comment: This might read better: You need to manage versioning/deployment of rules --------------------------------- Page 25, 4.2.1. Rules are assets Text: 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" (i.e. 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. Comment: Can we reword this to: As the BRMS can manage many different types of rules and other rules-related data, which are referred to as "assets". An asset is anything that can be stored as a version in the repository. This includes decision tables, models, DSLs and more. In this guide and in the UI, the word "rule" is sometimes used mean "asset" (i.e. the actions you can perform on rules can also be performed on the other asset types). Assets are grouped together for viewing, or to make a package for deployment. --------------------------------- Page 31, 4.2.4.1.3. A more complex example: Text: In the above example, you can see it is using a mixture of literal values, and formulas. The second constraint on the "Person" fact, is a formula (in this case it is doing a silly calculation on the persons age, and checking something against their name - both "age" and "name" are fields of the Person fact in this case. In the 3rd line (which says "age is less than .." - it is also using a formula, although, in this case the formula does a calculation and returns a value (which is used in the comparison) - in the former case, it had to return True or False (in this case, its a value). Obvious formulas are basically pieces of code - so this is for experienced users only. Comment: Can we reword the last line to: "Formulas are pieces of executable code - so this is for experienced users only." --------------------------------- Page 34, Section 4.2.4.5. Technical rules (drl) Text: Technical (drl) rules are stored as text - they can be managed in the BRMS. A DRL can either be a whole chunk of rules, or an individual rule. if its an individual rule, no package statement or imports are required (in fact, you can skip the "rule" statement altogether, just use "when" and "then" to mark the condition and action sections respectively). Normally you would use the IDE to edit raw DRL files, since it has all the advanced tooling and content assistance and debugging, however there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you generally have a been for some "technical rules" - you can mix and match all the rule types together of course. Comment: Can we reword this as: Technical (drl) rules are stored as text and can be managed in the BRMS. A DRL can either be an individual rule or multiple rules. If it's an individual rule, no package statement or imports are required. You can skip the "rule" statement altogether and just use "when" and "then" to mark the condition and action sections respectively. Normally you would use an IDE to edit raw DRL files, since it has all the advanced tooling to support editing, content assistance and debugging. Also - we have to ask Michael what this means - how does a rule being "technical" require that it be edited in the BRMS? However there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you generally have a been for some "technical rules" - you can mix and match all the rule types together of course. --------------------------------- Page 35, Section 4.2.4.7. Data enumerations (drop down list configurations) Text: Data enumerations are an optional asset type that technical folk can configure to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to. Comment: Can we reword the paragraph to read: Data enumerations are an optional asset type that can be configured to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to. --------------------------------- Page 37, 4.2.4.8. Advanced enumeration concepts Text: Mode advanced enumerations: In the above cases, the values in the lists are calculated up front. This is fine for relatively static data, or small amounts of data. Imagine a scenario where you have lists of countries, each country has a list of states, each state has a list of localities, each locality has a list of streets and so on... You can see how this is a lot of data, and it can not be loaded up. The lists should be loaded dependent on what country was selected etc... Well the above can be addressed in the following fashion: Comment: We should remove the "..." and the "Well" --------------------------------- Page 38, 4.2.7. Package management Text: Configuring packages is generally something that is done once, and by someone with some experience with rules/models. Generally speaking, very few people will need to configure packages, and once they are setup, they can be copied over and over if needed. Package configuration is most definitely a technical task that requires the appropriate expertise. Comment: I will ask Michael Neale about this one - I would like for us to be able tell readers which type of user should perform this task. Text: So whilst rules (and assets in general) can appear in any number of categories, they only live in one package. If you think of the BRMS as a file system, then each package is a folder, and the assets live in that folder - as one big happy list of files. When you create a deployment snapshot of a package, you are effectively copying all the assets in that "folder" into another special "folder". Comment: Can we remove the reference to "one big happy list of files?" -------------------------------- Page 39, 4.2.7. Package management Text: One of the most critical things you need to do is configure packages. This is mostly importing the classes used by the rules, and globals variables. Comment: Should be reworded to: One of the most critical tasks you need to do is configuring packages. This task consists of importing the classes used by the rules, and defining global variables. Text: Finally you would "build" a package. Any errors caught are then shown at this point. If the build was successful, then you will have the option to create a snapshot for deployment. You can also view the "drl" that this package results in. WARNING: in cases of large numbers of rules, all these operations can take some time. Comment: After importing the package's classes and defining its global variables, you build the package. If the build is successful, then you will have the option to create a snapshot for deployment. You can also view the "drl" that is generated when the package is built. Comment: Can we convert the WARNING text into a warning? Text: It is optional at this stage to enter the name of a "selector" - see the admin section for details on how to configure custom selectors for your system (if you need them - selectors allow you to filter down what you build into a package - if you don't know what they are for, you probably don't need to use them). Comment: We should remove this text as selectors are tech preview in this BRMS release. --------------------------------- Page 41, 4.2.8. Version management Text: Both assets and whole packages of assets are versioned in the BRMS, but the mechanism is slightly different. Individual assets are saved a bit like a version of a file in a source control system. However, packages of assets are versioned "on demand" by taking a snapshot (typically which is used for deployment). The next section talks about deployment management and snapshots. Comment: Can we remove the words "a bit?" Text: Each time you make a change to an asset, it creates a new item in the version history. This is a bit like having an unlimited undo. You can look back through the history of an individual asset like the list above, and view it (and restore it) from that point in time. Comment: Can we remove the words "a bit?" --------------------------------- Page 41, 4.2.9. Deployment management Comment: The first line ("Snapshots, URLS and binary packages:") should be removed. Text: Refer to the section on the Rule Agent for details on how you can use these URLs (and binary downloads) in your application, and how rules can be updated on the fly. Comment: The Rules Agent is described in section: 4.6.1. The Rule Agent --------------------------------- Page 46, 4.4. The fact model (object model) Text: Why would you chose declared types over jar files: generally this reinforces the fact that the model "belongs" to the rulebase, rather then the application, and allows the model to have a life-cycle separate from the application. It also removed the hassle of keeping jar files in sync between rules and the applications that use the rules. Comment: Can we reword this as: Some advantages to choosing declared types over jar files is that this reinforces the fact that the model "belongs" to the rulebase, rather than to the application, and allows the model to have a life-cycle separate from the application. It also removes the hassle of keeping jar files in sync between rules and the applications that use the rules. --------------------------------- Page 19, Section 2.6.4. Customizing the BRMS Platform User Interface Text: The most common branding change is to replace the images jbossrules_hdrbkg_blue.gif and drools.gif. Respectively these images are the logo at the top of the interface and the site "favorites icon" Comment: The jbossrules_hdrbkg_blue.gif is displayed multiple times on the top of the UI display. --------------------------------- Page 25, 4.2.1. Rules are assets Text: 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" (i.e. 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. Comment: Can we reword this to: As the BRMS can manage many different types of rules and other rules-related data, which are referred to as "assets". An asset is anything that can be stored as a version in the repository. This includes decision tables, models, DSLs and more. In this guide and in the UI, the word "rule" is sometimes used mean "asset" (i.e. the actions you can perform on rules can also be performed on the other asset types). Assets are grouped together for viewing, or to make a package for deployment. --------------------------------- Page 28, 4.2.4.1. Business rules with the guided editor Text: IMPORTANT: to use the BRL guided editor, someone will need to have you package configured before hand. Comment: I think that this is trying to say: IMPORTANT: To use the BRL guided editor, your account must first have package access configured. --------------------------------- 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. --------------------------------- Page 29, 4.2.4.1. Business rules with the guided editor Text: 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. Comment: Replace its with it's. --------------------------------- Text: 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"). E: This shows the constraint for the "age" field. (Looking from left to right) the green triangle allows you to "assign" a variable name to the "age" field, which you may use later on in the rule. Next is the list of constraint operations - this list changes depending on the data type. After that is the value field - the value field will be one of: a) a literal value (e.g. number, text), b) a "formula" - in which case it is an expression which is calculated (this is for advanced users) or b) a variable (in which case a list will be provided to choose values from). After this there is a horizontal arrow icon, this is for "connective constraints" : these are constraints which allow you to have alternative values to check a field against, for example: "age is less than 42 or age is not equal to 39" is possibly this way. 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). Comment: These are large/dense blocks of text. It would be easier to read if the paragraphs were reformatted - perhaps into tables: 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) * "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"). E: This shows the constraint for the "age" field. (Looking from left to right) the green triangle allows you to "assign" a variable name to the "age" field, which you may use later on in the rule. Next is the list of constraint operations - this list changes depending on the data type. After that is the value field - the value field will be one of: * a literal value (e.g. number, text) * a "formula" - in which case it is an expression which is calculated (this is for advanced users) or b) a variable (in which case a list will be provided to choose values from). After this there is a horizontal arrow icon, this is for "connective constraints" : these are constraints which allow you to have alternative values to check a field against, for example: "age is less than 42 or age is not equal to 39" is possibly this way. 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). Comment: I think that we should remove the reference to "advanced users only" as we do not define or document what it means to be an advanced user in this guide. --------------------------------- Page 30, 4.2.4.1.2. Augmenting with DSL sentences Comment: If the package the rule is part of has a DSL configuration, when when you add conditions or actions, then it will provide a list of "DSL Sentences" which you can choose from - when you choose one, it will add a row to the rule - where the DSL specifies values come from a user, then a edit box (text) will be shown (so it ends up looking a bit like a form). This is optional, and there is another DSL editor. Text: See attached screensho "DSL.jpg" - is this the DSL editor the text refers to? --------------------------------- Page 31, 4.2.4.1.3. A more complex example: Text: In the above example, you can see it is using a mixture of literal values, and formulas. The second constraint on the "Person" fact, is a formula (in this case it is doing a silly calculation on the persons age, and checking something against their name - both "age" and "name" are fields of the Person fact in this case. In the 3rd line (which says "age is less than .." - it is also using a formula, although, in this case the formula does a calculation and returns a value (which is used in the comparison) - in the former case, it had to return True or False (in this case, its a value). Obvious formulas are basically pieces of code - so this is for experienced users only. Comment: Can we reword the last line to: "Formulas are pieces of executable code - so this is for experienced users only." --------------------------------- --------------------------------- Page 34, Section 4.2.4.5. Technical rules (drl) Text: Technical (drl) rules are stored as text - they can be managed in the BRMS. A DRL can either be a whole chunk of rules, or an individual rule. if its an individual rule, no package statement or imports are required (in fact, you can skip the "rule" statement altogether, just use "when" and "then" to mark the condition and action sections respectively). Normally you would use the IDE to edit raw DRL files, since it has all the advanced tooling and content assistance and debugging, however there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you generally have a been for some "technical rules" - you can mix and match all the rule types together of course. Comment: Can we reword this as: Technical (drl) rules are stored as text and can be managed in the BRMS. A DRL can either be an individual rule or multiple rules. If it's an individual rule, no package statement or imports are required. You can skip the "rule" statement altogether and just use "when" and "then" to mark the condition and action sections respectively. Normally you would use an IDE to edit raw DRL files, since it has all the advanced tooling to support editing, content assistance and debugging. Also - we have to ask Michael what this means - how does a rule being "technical" require that it be edited in the BRMS? However there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you generally have a been for some "technical rules" - you can mix and match all the rule types together of course. --------------------------------- Page 37, 4.2.5. Templates of assets/rules Text: Tip: As you may have many similar rules, you can create rule templates, which are simply rules which are kept in an inactive package - you can then categories templates accordingly, and copy them as needed (choosing a live package as the target package). Comment: Can we convert this 'tip' into a note as defined in the orange box on page vii? --------------------------------- Page 39, 4.2.7. Package management Text: One of the most critical things you need to do is configure packages. This is mostly importing the classes used by the rules, and globals variables. Comment: Should be reworded to: One of the most critical tasks you need to do is configuring packages. This task consists of importing the classes used by the rules, and defining global variables. Text: Finally you would "build" a package. Any errors caught are then shown at this point. If the build was successful, then you will have the option to create a snapshot for deployment. You can also view the "drl" that this package results in. WARNING: in cases of large numbers of rules, all these operations can take some time. Comment: After importing the package's classes and defining its global variables, you build the package. If the build is successful, then you will have the option to create a snapshot for deployment. You can also view the "drl" that is generated when the package is built. Comment: Can we convert the WARNING text into a warning? Text: It is optional at this stage to enter the name of a "selector" - see the admin section for details on how to configure custom selectors for your system (if you need them - selectors allow you to filter down what you build into a package - if you don't know what they are for, you probably don't need to use them). Comment: We should remove this text as selectors are tech preview in this BRMS release. --------------------------------- Page 41, 4.2.8. Version management Text: Both assets and whole packages of assets are versioned in the BRMS, but the mechanism is slightly different. Individual assets are saved a bit like a version of a file in a source control system. However, packages of assets are versioned "on demand" by taking a snapshot (typically which is used for deployment). The next section talks about deployment management and snapshots. Comment: Can we remove the words "a bit?" Text: Each time you make a change to an asset, it creates a new item in the version history. This is a bit like having an unlimited undo. You can look back through the history of an individual asset like the list above, and view it (and restore it) from that point in time. Comment: Can we remove the words "a bit?" --------------------------------- Page 46, 4.4. The fact model (object model) Text: Why would you chose declared types over jar files: generally this reinforces the fact that the model "belongs" to the rulebase, rather then the application, and allows the model to have a life-cycle separate from the application. It also removed the hassle of keeping jar files in sync between rules and the applications that use the rules. Comment: Can we reword this as: Some advantages to choosing declared types over jar files is that this reinforces the fact that the model "belongs" to the rulebase, rather than to the application, and allows the model to have a life-cycle separate from the application. It also removes the hassle of keeping jar files in sync between rules and the applications that use the rules.
From Michael - thanks! Try this: Technical (drl) rules are stored as text - they can be managed in the BRMS. A DRL can either be a whole chunk of rules, or an individual rule. if its an individual rule, no package statement or imports are required (in fact, you can skip the "rule" statement altogether, just use "when" and "then" to mark the condition and action sections respectively). Normally you would use the IDE to edit raw DRL files, since it has all the advanced tooling and content assistance and debugging. However, there are times when a rule may have to deal with something fairly technical in a package in Guvnor. In any typical package of rules, you generally have a need for some "technical rules" - you can mix and match all the rule types together of course. Len DiMaggio wrote: > Hey Michael, > > Question on something in the user guide - can you add to this? > > > Page 34, Section 4.2.4.5. Technical rules (drl) > > Text: > > Technical (drl) rules are stored as text - they can be managed in the BRMS. A DRL can either be a > whole chunk of rules, or an individual rule. if its an individual rule, no package statement or imports > are required (in fact, you can skip the "rule" statement altogether, just use "when" and "then" to mark > the condition and action sections respectively). Normally you would use the IDE to edit raw DRL files, > since it has all the advanced tooling and content assistance and debugging, however there are times > when a rule may have to deal with something fairly technical. In any typical package of rules, you > generally have a been for some "technical rules" - you can mix and match all the rule types together of > course. > > Comment: > > ------> How does a rule being "technical" require that it be edited in the BRMS? Maybe this needs rewording? > > However there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you > generally have a been for some "technical rules" - you can mix and match all the rule types together of > course.
Document has been updated with the above feedback. Feedback above has been incorporated with the exception of a couple of "formatting issues" (no time sorry) and the items below which need more information: Page 33, Section 4.2.4.3. Spreadsheet decision tables Text: To use a spreadsheet, you upload an xls (and can download the current version, as per the picture above). To create a new decision table, when you launch the rule wizard, you will get an option to create one (after that point, you can upload the xls file). Comment: We should also state that BRMS currently supports uploading from Microsoft Excel(tm) spreadsheets. --------------------------------- Is that to say we should specify that when we say xls we specifically mean Microsoft Excel(tm) spreadsheets? Page 36, 4.2.4.8. Advanced enumeration concepts Comment: The references to ULP and PULP types of fuel may be lost on readers who are not in Australia. Maybe we can add a footnote: http://www.fuelwatch.wa.gov.au/info/dsp_fuel_types.cfm --------------------------------- Examples in less specific domains would be preferred but adding further clarification is not really necessary. The description of the problem domain is fairly clear. Page 20, 2.6.5. Import and Export We've seen failures on importing large repos. We may need to add some additional warnings to this section. Let's talk to Darrin about how to describe this. --------------------------------- what sort of errors? are there any plans to address this? JIRA? should I include it as a known issue in the release notes?