XML References Editor
XML References Editor allows you to create links between application’s XML data fields and the RuleLab.Net Atoms. At runtime, XML References are used by the BRE to evaluate Atoms through pulling data values from your application XML document. RuleLab.Net stores References in an XML file that is created/updated when you save them in the Reference Editor. To bring up the Editor, load your project and click the References tab.
The References Editor displays a grid of rows each representing a single XML Reference. A Reference includes the following fields:
§ Alias – globally unique name identifying this Reference to the RuleLab.Net.
§ XML Node Path – an XPath expression referring to XML node(s) in application’s data document
§ Type – the field type of your node that RuleLab.Net should apply to in order to format Fact and Constant data entry. The supported types are: text, numeric, date, time, currency. The BRE checks application data syntax against its type at runtime.
§ Atom checkbox – this is a shortcut that exposes this Reference to the Rules Editor as a single Reference Atom – without you actually creating an Atom in the Atoms Editor.
§ Loop (parent node) – if this node is part of a loop, then enter a full path of the Parent node containing the loop items. Specifying nodes as loops enables filters, aggregate and other RuleLab.Net functions. Nested loops are not supported.
§ Overwritable – you have an option of marking a Reference (single-reference Atom) “overwritable” in which case the Rules Conflict issue will not apply to it. Such Atoms can be changed by any Rule at the time it is fired. For example, you may want to mark “Total” Atom as an overwritable if it can be subsequently altered by several rules/formulas. Or, you would want to make “UserMessage” Atom an overwritable if multiple rules can add additional text messages to it.
|
For example, consider the following application XML data sample:
<customer> <customerID>JNC136</customerID> <purchases> <item> <partNumber>17878</partNumber> <price>420.00</price> <date>9/10/2005</ date> </item> <item> <partNumber>5343</partNumber> <price>315.00</price> <date>1/10/2006</ date> </item> <item> <partNumber>6700</partNumber> <price>280.00</price> <date>2/1/2006</ date> </item> </purchases> </customer>
To link this data with RuleLab.Net we could create the following References:
Customer ID: XML Path: customer/customerID Type: text
Part Number: XML Path: customer/purchases/item/partNumber Parent Loop Path: customer/purchases Type: numeric
Price Paid: XML Path: customer/purchases/item/price Parent Loop Path: customer/purchases Type: currency
Purchase Date: XML Path: customer/purchases/item/date Parent Loop Path: customer/purchases Type: date
This definition would allow us to write a Rule such as “If Customer made at least 2 purchases since 1/1/2006 for a total amount exceeding $500 then give Customer a 10% discount coupon”. You could also set up a rule as “evaluate for each loop” which would let you apply it individually to every “item”.
|
|
The Editor screen offers commands for adding more Reference rows, inserting/moving/deleting rows, and adding/changing section titles. When an existing project is loaded, References that are utilized in the currently loaded Atoms and Rules (if Reference is marked as an Atom) are rendered in blue. The Editor restricts changes that can be made to these References.
Once References are entered, you can utilize them for creating Atoms.
Using an Application XML data document sample
You can upload your XML data document to the Reference Editor. To upload, click the “Upload XML Application File” button and select the XML data template file on your local drive. Your document will be rendered as a tree of XML nodes – same nodes you are creating the References for. Having the source tree on the screen allows easy entry of default XPath expressions. The default expression is simply the full path to an XML node. But you don’t have to type the path in. Just select the target Reference table row, click your XML data element node and press the “Copy Node Path” button. If this node belongs to a loop, you can copy the loop parent node path using the “Copy Loop Parent Path” button. Without changing the row, click the loop parent tree node then click the “Copy Loop Parent Path” button.
If you wish you can alter the expressions created via the “Copy” buttons. Please follow the XPath guidelines when changing or entering expressions.
You still have to enter a Reference Alias and select its Type.
Note that the XML document you upload should conform to the schema of the XML data documents you are planning on passing to the BRE. Same document you upload here can be utilized in the Test screen. Of course the Test screen requires actual data while Reference screen does not.
Application Data XML document you upload to the References screen is not stored on our server. It is only intended to assist you with referencing application data node paths. No relations are being explicitly created between this document and your References. Every time you wish to update the References, you can re-upload an Application Data XML document. If your schema changes and so does your XML data model, you can re-upload and put your References in sync with changes by simply selecting nodes/rows and clicking the Copy buttons. If there are structural changes that go beyond path/node name updates you will have to do more work in the References screen and possibly in the Atoms, Facts and Rules screens as well.
Special care should be taken when changing References utilized in files not loaded into the current Project. RuleLab.Net allows you to have multiple Atoms files related to a single References file but only one set of Atom and Rule files will be loaded at the time of the change. To assist with the system integrity, RuleLab.Net checks Reference changes against the other files of the Project but it can do nothing about Atoms/Rules files not currently loaded.
If your application XML structure changes, you will most likely have to update the XML References. Once changes are made, you will need to load each affected Project into the Editor and let the system point out the discrepancies in the Atom, Fact and Rule definitions. You can then correct each and save the files. Note that it’s up to you as the RuleLab.Net administrator to keep track of all the files and file copies that you want to maintain.
If you erase Reference’s loop container node name, then the associated Atoms will loose their Loop status. However, they might already be entered into some Rules as loops. Such entries must get corrected in every Rule. The correction will not happen automatically. You will either have to Validate each Rules file against the changes you have made OR let the system do it for you when you load the project. In either case, please follow each error message to correct the Rules.
If you change the Reference’s loop container node path then some Atoms may become invalid since they might now be referencing application XML nodes that belong to the different loops. In RuleLab.Net, all loop References within an Atom must belong to the same loop therefore you will have to remove either one of the conflicting References from an Atom. The removal will not occur automatically. You will have to explicitly Validate the Atoms file and correct the corresponding errors. The validation runs automatically when you load or reload the Project.
System References/Atoms
If you wish to create a temporary Atom without storing it in the application XML, leave the XML Node Path blank. At runtime, this Atom will be created in the BRE State.
The following system References/Atoms are created by default:
“exit” – allows you to stop the rules engine by setting the value to “Yes”. A corresponding Natural Term is automatically created in the Vocabulary.
Related topics