WebService

RuleLab.Net Web Service

Implementation Model

RuleLab.Net lets you execute the BRE via Web Service calls by passing in your Data, Rules, Facts, Atoms and XML References documents. All RuleLab.Net documents that you pass to the Web Service should have been validated in the Rules Designer. The RunBRE method allows an application to pass Rules and other documents by the online file name or by the XML document text. If you would like to load a document from the online database, then provide the online file name. If you have downloaded a document to your local machine then you can send its XML text instead. When choosing between the two options, please give your preference to the File Name based approach because it is much more efficient to pull large XML documents from the RuleLab.Net Server database then transmit them over the internet.

The Web Service returns an updated Data document and a State XML document. From the State document your application can check if any rules have fired, whether input data fields were missing, what fields prevented rules from firing, if rule conflicts have occurred. An application can supply the required field data and call the Web Service again. This loop should continue until the Application has no new data to supply and no rules have fired OR if the application goals have been reached. For more information see the BRE specification.

Each Web Service call returns the Status XML document.

Web Service Proxy

The Web Service description is available at http://www.rulelab.net/BREWebService.asmx

The Proxy class is available for download as part of the BREWebSvcSample package. You can generate the proxy class yourself using WSDL by running the following command:

wsdl /out:RuleLabBREWebSvcProxy.cs http://www.rulelab.net/BREWebService.asmx

Note for Customers hosting RuleLab.Net on their company server

Do not use the default proxy class because it will take your calls to www.rulelab.net where you do not have a login. Instead, generate the proxy class off your local RuleLab.Net server. For example, if your RuleLab.Net server name is “myserver” then run the following command to generate RuleLabBREWebSvcProxy.cs pointing to “myserver”:

wsdl /out:RuleLabBREWebSvcProxy.cs http://myserver/BREWebService.asmx

The Return Status

Every method of the RuleLab.Net Web Service, BRE assembly and COM returns the Status XML document. It includes execution errors if any. Two types of errors can be returned – system errors and data errors.

Here is the Status document template:

</BREStatus>

A successful execution is indicated by the “success” keyword in the <status> node:

<status>success</status>

</BREStatus>

If a system error or an XML structural error has been detected, it is reported in the <systemError> tag. The <status> node would be set to “failure”. System errors should not be displayed to the user since they indicate a problem with the software on either side. Example:

<status>failure</status>

This is an unexpected token. The expected token is 'TAGEND'. Line 5, position 3.

</systemError>

</BREStatus>

Data errors are returned by the RunBRE method which validates input data syntax against the XML Reference types. If the data item had been sent in a wrong format or if a date/time value is not a valid date/time then the BRE sends back an error message.

<dataErrorMessages> tag contains a list of <msg> tags each including

<alias> - RuleLab.Net XML Reference alias

<xpath> - XML path to the node as specified in the associated XML Reference

<text> - error message text

The following sample status document in returned in the response to an attempt to Run the BRE on an invalid date value and on an numeric type field containing a letter:

<status>failure</status>

</systemError>

<msg>

<alias>Final Pay Due Date</alias>

<xpath>reservation/finalPayDueDate</xpath>

<text>Invalid DATE value: 53/13/2006</text>

</msg>

<msg>

<alias>Number of Guests</alias>

<xpath>reservation/numberOfGuests</xpath>

<text>Data is not numeric: 4i</text>

</msg>

</dataErrorMessages>

</BREStatus>

The RetrieveErrors function in the TravelReservation.aspx.cs file is an example of parsing the Status. This file is a part of the Client Application package that you can download from the product demo page.

If you utilize the BRE for validating user entries, you may want to display data errors to users. Use either the Reference alias or the XML path to map an error message to your UI control.

Web Service Headers

1. Client Authentication header

Client authentication is required in order to run a Web Service method. Each Web Service call must include the “clientAuthentication” header containing the following:

String userID (required) – your RuleLab.Net admin user ID, the one that you created during the account registration

String password (required) – the login password

String encryptionKey (required if data is encrypted) – the encryption private key that you can look up in the Account/Encryption screen. Example: 11-222-33-444-55-6-77-888

2. Options header

The BRE State XML document may get very large if you let it return all of the available information. You can control the BRE State content using the <options> header:

Bool enableRuleEvaluationDetails – enable the collection of the rule processing details under the <evaluatedRules> tag of the BRE State. If set to true, this flag may trigger an accumulation of a very large amount of information which will affect the performance of your application if it evaluates hundreds of rules. Unless you use this information, always set this flag to false.

Bool enableRuleConflictsDetails – enable the collection of the Rule Conflict details under the <conflicts> tag of the BRE State. If set to true, this flag may trigger an accumulation of a very large amount of information which will affect the performance of your application if it evaluates hundreds of rules that target same non-overwritable data. Unless you use this information, always set this flag to false.

Web Service Methods

RunBRE – load XML documents into the BRE and execute the BRE pass

Return Status

This method returns the Status XML document like every other method. In addition to the success/failure and a system error message, it can also return data format errors as described in the “BRE Status” section.

Parameters

String type (optional) – “F” (default) for “Forward Chaining”

String references (required) – online file name or the full text of an XML document containing XML References

String atoms (required) – online file name or the full text of an XML document containing Atoms

String facts (required) – online file name or the full text of an XML document containing Facts

String vocabulary (reserved) – empty string

String rules (required) – online file name or the full text of an XML document containing Rules

String [] includeRules (optional) - an array of the Rules documents – the include-file names or the full text of the Rule XML documents to be merged with the “rules”. Rule IDs must be unique across all the Rule files in the Web Service call. If you are not including any files set the “includeFiles” to NULL.

Int [] includeRuleBasePriorities (optional) – an array of the offsets to add to every Rule priority within the corresponding “includeRules” document. The Priorities go from 1 to 10. If you pass a base value of 10 then the Rule priorities will be adjusted to 11 thru 20. The default value is 0.

String inXmlAppData (required) – the application Data XML document.

String inXmlBREState – the State document is required for the subsequent BRE pass calls within the BRE Session loop. Initially it can be set to NULL. This parameter is optional (NULL) if you are only making a one-pass call to the Web Service.

String outXmlAppData (required) – an output parameter for collecting the results of the BRE processing. Set it to a blank XML document. Upon the BRE return, it will contain a copy of the inXmlAppData document updated with the field data set by the BRE. The field updates are the result of Business Rules action execution. Please note that this parameter is the end goal of the entire RuleLab.Net system.

String outXmlBREState (required) – the output parameter for returning the BRE State required for subsequent calls to the BRE. Set it to blank XML document for the first call within the BRE Session. It must be copied to inXmlBREState before initiating the subsequent calls within the same Session. Your application can retrieve other important information from the outXmlBREState XML document.

GetReasoning – get an XML document showing the BRE reasoning process. The reasoning is derived from the XML State document returned by the previous call to the RunBRE method.

This method displays the rules that executed and the assignments that were made in order to set a particular variable. It expresses the BRE logic in terms of the rules that fired and the assignment details. For each rule that fired, its condition’s References are cross-referenced with the assigned variables in order to back track the inference process. The resulting XML looks like a tree with the rule nodes and atom nodes expanded to show the rules that were fired to resolve them to data.

GetReasoning is the same method that the Rules Designer Test screen calls to show the Reasoning. If you wish to implement this method please refer to the “Web Service Sample” project available for a download from the “Implementation” page of the Rules Designer. The file BREClient.aspx.cs contains “RenderReasoning” method that translates the Reasoning XML into HTML.

The following XML documents contain the specification of the BRE Reasoning:

BRE Reasoning XML Schema

BRE Reasoning XML document template

(note that this document is recursive and can expand as deep as the amount of rules you have in your project)

Important: enableRuleEvaluationDetails flag must be set to true in the Options Header in order to support the Reasoning. This flag instructs the BRE to collect Rule Evaluation information under the <evalualtedRules> tag. This information is required by the Reasoning logic. If <evalualtedRules> is sent empty, the GetReasoning method will error out.

Parameters

String varName (required) – the name of a variable (same as the Reference name) that was assigned a value by the BRE. It must be present under one of the <assignedData> tags within the XML State document (inXmlBREState parameter below). The resulting XML document will show the decision process that led to this assignment.

String references (required) – online file name or the full text of an XML document containing XML References

String atoms (required) – online file name or the full text of an XML document containing Atoms

String facts (required) – online file name or the full text of an XML document containing Facts

String rules (required) – online file name or the full text of an XML document containing Rules

String [] includeRules (optional) - an array of Rules documents – the include-file names or the full text of the Rule XML documents to be merged with the “rules”. Rule IDs must be unique across all the Rule files in the Web Service call. If you are not including any files set the “includeFiles” to NULL.

String inXmlAppData (ignored) – set to blank.

String inXmlBREState (required) – the BRE State document from the latest BRE pass.

String outXmlReason (required) – the output parameter for returning the BRE Reasoning.

DownloadFile – download XML file. This method, along with the GetDateTimeChanged() method, are provided for synchronizing the offline BRE XML documents with the online updates.

Parameters

String fileName (required) – name of the XML file in the online database

String fileText (required) – output parameter for the XML document text

GetDateTimeChanged – get the time stamp of the most recent online file update. This method, along with the DownloadFile() method, are provided for synchronizing the offline BRE XML documents with the online file updates.

Parameters

String fileName (required) – name of the XML file in the online database

DateTime dtLastUpdated (required) – output parameter for the timestamp (server local time).

RunBRE2 – same as RunBRE plus allows the application to select the rules to run

(See RunBRE)

String ruleSelection (optional) – XML document containing the rule selections. Only the listed rules will be evaluated. The rest will be ignored. If you wish to overwrite the default rule order and priorities assigned via the Rules Designer, then set the "overwriteOrder" attribute to "yes". Rule Selection XML can be tested via the "Select Rules" link of the Test Screen.

Select the rules by entering rule identifiers into <ruleID> tags. Alternatively, you can select entire rule sections by entering section titles into <ruleSection> tags. Selecting a section is equivalent to listing its rule identifiers in the order they appear in the rule list.

Rule selection XML document example:

<ruleSection>section title 1</ruleSection>

<ruleSection>section title 12</ruleSection>

</selectRules>