Hide Forgot
Affects: Documentation (Ref Guide, User Guide, etc.) Date of First Response: 2009-09-08 00:40:57 securitylevel_name: Public Use this JIRA to collect comments on BRMS 5.0.1 User Guide. Document is here: https://svn.devel.redhat.com/repos/jboss-soa/trunk/build-tools/docs/BRMS/
Document is not included in the CR1 build - will be reviewed from: https://svn.devel.redhat.com/repos/jboss-soa/trunk/build-tools/docs/BRMS/
Link: Added: This issue depends BRMS-134
Link: Added: This issue is related to BRMS-221
Link: Removed: This issue is related to BRMS-221
Link: Added: This issue is a dependency of GUVNOR-451
Comments: page 1, 1.2. When to use a BRMS Text: The JBoss Enterprise BRMS Platform can be "branded" for integration into another application, or it can be used as a central rule repository. Comment: I think we should remove this text. It's out of place here, and there is no supporting information to explain to the reader how the "branding" is done. ------------------- page 3, 2.1. Supported and Recommended Platforms We should add a pointer to this URL: http://www.jboss.com/products/platforms/brms/testedconfigurations/ ------------------- page 3, 2.2. Installation Comment: We have to be sure to tell the users to install BRMS into the EAP production server profile. Trying to run BRMS on the default configuration results in this exception: java.lang.NoClassDefFoundError: org/jgroups/MembershipListener at java.lang.ClassLoader.defineClass1(Native Method) at java.lang.ClassLoader.defineClass(ClassLoader.java:621) ------------------- page 4 Figure 2.1. BRMS Login - this figure is missing Figure 2.2. BRMS first screen after login - this figure is missing too ------------------- page 7, 2.3.2. BRMS Database Configuration Text: For specific details on which Databases are supported you should refer to the "Supported Deployment Platforms" section of the Release Notes. Comment: We should add a pointer to this URL: http://www.jboss.com/products/platforms/brms/testedconfigurations/ ------------------- page 11, 2.4.1. Authentication Example - UserRolesLoginModule Text: 3. Configure the JBoss Login Module JBoss Login Modules are configured in the file ${INSTALL}/JBoss-as/server/${CONFIG}/ conf/login-config.xml. Open this file in an editor. It is an XML file containing a <policy> element with several <application-policy child elements. Each <application-policy element defines a different authentication scheme. Add the following <application-policy XML snippet as a new child of the <policy> element. Comment: The XML snippet is missing - and <application-policy should have a closing ">". ------------------- page 12, 2.4.2. Authentication Example - LDAP Text: You can get additional information about different LDAP configuration scenarios at http://wiki.JBoss.org/wiki/Wiki.jsp?page=LdapLoginModule and http://wiki.JBoss.org/wiki/Wiki.jsp?page=LdapExtLoginModule. Comment: The links are here: http://www.jboss.org/community/wiki/LdapLoginModule http://www.jboss.org/community/wiki/LdapExtLoginModule ------------------- page 21, Figure 3.1. Architectural diagram Comment: In the diagram, separate is misspelled as "seperate." ------------------- page 23, 4.1.1. Supported Browsers Comment: The browser version numbers are spelled out as words (e.g., "Firefox three" instead of "Firefox 3." Comment: Actually, we should just remove this section. The information has already been covered in the document. ------------------- page 24, 4.1.3. Writing Some Rules Text: You create a rule by clicking the icon with the rules logo (the head) and, from, that you enter a name. Comment: The head logo is in the display. ------------------- page 28, 4.2.3. The Asset Editor Text: This is the documentation area - a free text area where descriptions of the rule reside. Red Hat strongly encourage you to write a plain description in the rule here before editing. Comment: Replace "encourage" with "encourages." ------------------- page 42, 4.2.9. Deployment Management Text: URLs are central to the process surrounding how built packages are provided. The BRMS provides packages via URLs for download and use by the Rule Agent. These URLs take the form of: http:// <server>/jboss-brms/org.drools.guvnor.Guvnor/package/<packageName>/<packageVersion> Comment: In section 2.2. Installation, we tell the user to install the BRMS war as: http://localhost:8080/JBoss-BRMS/ The above URL of http://<server>/jboss-brms/ will fail ------------------- page 45, 4.3. Creating a Business User View Text: Most of the time, not all of your users will want to see the full extent of functionality described here. It may be that you have a subset of users whose permissions you wish to limit to viewing or edit certain sets of rules. Comment: Replace "edit" with "editing." ------------------- page 50, 4.7. WebDAV and HTTP Text: http://10.64.5.95:8080/jboss-brms/org.drools.guvnor.Guvnor/webdav/ Comment - this - and all other URLS have to change to match section 2.2 ------------------- page 55 - "Important" note Text: The default URL supplied by EGT in the Connection Wizard is not correct for the default URL used by the JBoss Enterprise BRMS Platform. The correct URL to use is: http:// localhost:8080/jboss-brms/org.drools.guvnor.Guvnor/webdav Comment - again - the URL must match that documented in section 2.2 ------------------- Multiple figures/screenshots in the EGT section use the Guvnor project url: http://localhost:8080/drols-guvnor.... Figure 5.10. Properties Figure 5.11. Add action Figure 5.12. Add action Figure 5.17. History Figure 5.18. Import Figure 5.19. Import Figure 5.22. Preferences ------------------- Page 69, Appendix A. Example Persistence Manager configurations Text: Important The 5.0 release of the JBoss Enterprise BRMS Platform only supports Oracle as a database provider. Comment: For a list of supported databases, we should direct readers to: http://www.jboss.com/products/platforms/brms/testedconfigurations/
In section 2.2. Installation, we tell the user to install the BRMS war as: http://localhost:8080/JBoss-BRMS/ instead of http://localhost:8080/jboss-brms/ (as was the case in the 5.0 GA release) as a result many other edits to the document are needed. (See the above comment.) Is there a need to change the URL on 5.0.1? If not, then we should restore the text to: http://localhost:8080/jboss-brms/
Assigned back to David to make the edits.
All changes have now been undertaken.
Assigned back to Len to check. (I will need to add the updated version to the site.)
Now redeployed to site.
Resolving - assigning to myself to verify in the CR2 docs.
Two important final changes are needed to the guide: ---------------------------------- page 3, 2.2. Installation Comment: We have to be sure to tell the users to install BRMS into the EAP production server profile. Trying to run BRMS on the default configuration results in this exception: java.lang.NoClassDefFoundError: org/jgroups/MembershipListener at java.lang.ClassLoader.defineClass1(Native Method) at java.lang.ClassLoader.defineClass(ClassLoader.java:621) Sorry - I was unclear in a previous review - the note about installing into the production profile should remain. The NoClassDefFoundError error message should be removed from the guide. ---------------------------------- In section 2.2. Installation, we tell the user to install the BRMS war as: http://localhost:8080/JBoss-BRMS/ instead of http://localhost:8080/jboss-brms/ (as was the case in the 5.0 GA release) Please be sure to change this section to refer to installing the BRMS war as http://localhost:8080/jboss-brms/
Len, I removed the error message. I can't find any part of Section 2.2 or anywhere else taht referes to http://localhost:8080/JBoss-BRMS/ . They all seem to be lower case now. Can you please clarify where you saw this? Many thanks.
Seeing it here: Pages 3 and 4: ======================== 2. The JBoss Enterprise BRMS™ platform package contains two files, JBoss-BRMS-manager.zip and JBoss-BRMS-engine.zip. JBoss-BRMS-manager.zip contains JBoss-BRMS.war. JBoss-BRMS.war is the Java web archive containing the BRMS application. JBoss-BRMS-engine.zip contains the jar files for the JBoss Rules 5 rules engine. These are the jar files required for building client applications using JBoss Rules 5. Extract the file JBoss-BRMS.war to a temporary directory. You can simply deploy this web archive to your JBoss EAP server but you will be unable to configure it. Chapter 2. Updated BRMS Installation and Administration "explode" the web archive 3. Create a directory called JBoss-BRMS.war and use a file archive tool to unpack the web archive into this directory.
The correct file name is: jboss-brms.war
Just fixed these. Didn't initially realise the war file itself had to be corrected as well as the URL. Now fixed but not uploaded as we are doing some more work on the documents before publishing a new version to the server.
Some more comments Why is JBoss *everywhere* in bold? page 3: Microsoft in bold https://support.redhat.com/JBossnetwork/ lowercase JB in JBoss page 4: If a new registry was created you will also ... it's a repository, not a registry page 7 and 8: Ensure that the BRMS Platform is not running, either by un-deploying it or halting your JBoss EAP server. You have to stop the EAP before you do step #2 (copying classes into the lib direcotry, otherwise you end up with a ClassNotFoundException page 8: Eg. ${INSTALL}/server/production/lib/ jboss-as dir is missing Eg. ${INSTALL}/jboss-as/server/production/lib/ page 11: org.JBoss.security.auth.spi.UsersRolesLoginModule should be lowercase JB directory ${INSTALL}/JBoss-as/server lowercase JB (several times on this page) step #3 and #4: missing sample xml snippets page 13, step #3: missing sample xml snippets page 14: This panel can be found be going to the Navigate panel 'be' should be 'by' page 15: The permissions assigned to a use can be updated 'use' should be 'user' page 18: from the BRMSWAR file no space between BRMS and WAR page 23: feature areas mentioned below figure 4.1 not in sync with this figure page 26: is a still a single category one 'a' needs to be removed page 27: and this action this will create a new item second 'this' needs to be removed does not effect its execution 'effect' should be 'affect' page 30: figure 4.6, 4.7, 4.8, 4.9, 4.10, 4.17, 4.18, 4.23 from old jbrms page 40: The picture bove shows 'bove' should be 'above' page 44: shows the alternativee way of exploring 'alternativee' should be 'alternative'
page 47: those dervied from using 'dervied' should be 'derived' page 48: IMPORTANT: ... This section should be in orange I guess. page 49: see the "Package URI" 'Package URI' should be 'Deployment URL' then replace "NewSnapshot" with "LATEST". 'NewSnapshot' should be 'TEST' page 50: There are also many third-party WebDav clients are available double 'are' http://10.64.5.95:8080/jboss-brms localhost, <server> and <yourserver> is used everywhere else page 53: that are be the center doesn't sound correct... that *is* the center? *they* are the center? page 57: one the tool-bar these are 'one' should be 'on' page 58: There are two method of should be 'methods' page 62: Not that the wizard will not allow 'Not' should be 'Note'
All above feedback has been incorporated except figure 4.6, 4.7, 4.8, 4.9, 4.10, 4.17, 4.18, 4.23 Due to time constraints these will probably not make the deadline. If not I'll log a JIRA for them in CP02 and try to get them done as soon as possible to update the CP01 online docs.
Assigning to QE to verify
2198e7fc078b1affcd24b2d0c2b5fc90 BRMS_Userguide.pdf Verified. Logged remaining issues in BRMS-233.
Verified - remaining issues in BRMS-233.
updated doc to include BRMS-227
Link: Removed: This issue is a dependency of GUVNOR-451