Package: ruleau
RuleauA Python Rules Engine libraryUsing the libraryA username and password is required. This can be passed directly to the ApiAdapter (i.e. via the CLI) or these can
be set in the environment variables.RULEAU_USERNAME=myusername
RULEAU_PASSWORD=mypasswordfromruleauimportexecute,rule,ApiAdapter,Process# create a rule@rule(rule_id="rul_1",name="Is adult")defover_18(_,payload):return"age"inpayloadandpayload["age"]>=18# create a payload (the answers to the rule's questions)payload={"age":17}# execute the rule against the payloadresult=execute(over_18,payload,Process.create_process_from_rule(over_18))# integrate with the backend web API with password and username in envapi_adapter=ApiAdapter(base_url="http://localhost:8000/")# or pass directly to ApiAdapter:api_adapter=ApiAdapter(base_url="http://localhost:8000/",username=myusername,password=mypassword)# sync the process# Usually only needed once. For efficiency, it is advisable to keep these lines out of any loop.process=Process.create_process_from_rule(over_18)api_adapter.sync_process(process)# send the resultsresult=execute(over_18,payload,process,api_adapter=api_adapter,case_id="ca_1280")# result.result will be False due to applicant being 17# if the rule for this case is overriden in the backend# then running again will return TrueOrganisational DataOptionally a Process can be assigned as set of "tags" called Organisational Data which can be used
to filter or categorise rules and results.Each Process must have these specified up front by setting the Organisational Scheme like so:api_adapter=ApiAdapter(base_url="http://localhost:8000",)org_scheme:List[OrganisationalScheme]=[OrganisationalScheme(id="location",# ID Used to refer to the tag when organisational data is posteddisplay_name="Location",# Label used on the UI when being displayeddisplay_default=True,# If true, will appear on the UI by default, otherwise is hiddentype="string",# Either a `string`, `integer`, `float` or `date` type),OrganisationalScheme(id="internal_id",# ID Used to refer to the tag when organisational data is posteddisplay_name="ID",# Label used on the UI when being displayeddisplay_default=True,# If true, will appear on the UI by default, otherwise is hiddentype="integer",# Either a `string`, `integer`, `float` or `date` type)]api_adapter.publish_organisational_scheme(over_18,org_scheme)Once set data can be provided when a ruleset is executed by updating the API Adapter using itswith_organisational_datamethod like so:api_adapter=ApiAdapter(base_url="http://localhost:8000/").with_organisational_data([{"key":"location","value":"Bristol"},{"key":"internal_id","value":5}])process=Process.create_process_from_rule(over_18)api_adapter.sync_process(process)result=execute(over_18,payload,process,api_adapter=api_adapter,case_id="ca_1280")Optionally we can also set the order by which Organisational Data appears on the UI by posting
to the UI Layout Metadata endpoint as in this example:ui_layout_metadata:UiLayoutMetadata={# Defines the order the tags will appear on the cases page"case_org_data_order":[{"id":"internal_id"},{"id":"location"}],# Defines the order the tags will appear on the overrides page"override_org_data_order":[{"id":"department"}],# See "Case Payload UI Specification" for details"data_payload_presentation":None,}api_adapter.publish_ui_layout_metadata(payload_has_patient_rule,ui_layout_metadata)Case Payload UI SpecificationIn the Ruleau UI we display the case payload as it was executed for a case, and allow users to override the data
with values when said case is next reexecuted.By default we work out the structure of case payload automatically to display it in the UI, this will perform basic
validation such as checking if the data override provided for a case matches the type in the original payload.However you can use UI Layout Metadata to publish a JSON Schema specification that defines how case payloads for a
process should be displayed and validated, allowing for customisation of what overrides can be specified for the data.In order to do this, please see the below example setting a JSON Schema for a case:ui_layout_metadata:UiLayoutMetadata={# See "Organisational Data" for details"case_org_data_order":[],# See "Organisational Data" for details"override_org_data_order":[],# X"data_payload_presentation":{"type":"object","properties":{"street_address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"}},"required":["street_address","city","state"]},}api_adapter.publish_ui_layout_metadata(payload_has_patient_rule,ui_layout_metadata)The above example tells the UI a case payload for this process is expected to have 3 fields:street_addresscitystateAll 3 of them are required text fields, and can be overridden on a case by case basis in the UI.JSON Schema Rules & LimitationsAs a JSON Schema could define any shape of data, even one wildly different from the case payloads posted for a process,
we have to impose set of rules & limitations to ensure they are compatible with the payloads displayed on the UI.On a case payload please always provide all the keys, even if null, rather than excluding the keys with no valuesFor example please use{"a": null, "b": "abc"}over{"b": "abc"}ifais optionalA custom JSON schema must only define one type for a given propertyWe don't support multiple types in a single fieldLists containing both strings and numbers aren't allowedNor are properties that can be either a string or number, for exampleEverything in the custom JSON schema must be in the payloadNo fields should exist in the schema that aren't on the payloadsFor example if the schema specifies a fielda, that field should be present in all case payloads, even if nullHowever not everything in the payload has to be in the JSON schemaFor example the payload may have fieldsa,bandc, however you only wish fieldbto be editableIn that case, adding just thebfield to the Schema means that is the only field the UI will allow data overrides forIf a custom JSON schema isn't defined, and a field is alwaysnullin a case, it won't be shown on the data overrides UIThis is as we are not able to generate a JSON schema from anullfield (we cannot tell what type is required)This can be resolved by using a custom JSON schema and specifying what the field should be when notnullIn the example below the payload has anullwind_sensorfield, by specifying it in the schema it can still be edited in the UIPlease see below for an example of a custom JSON schema and the expected case payload:Case Payload{"case_id":"001","temperature":27,"wind_speed":0.4,"humidity":30,"cloud_cover":20,"precipitation":0,"last_checks":[],"pending_checks":[],"sensor_status":{"wind_sensor":null,"cloud_reader":null,"rain_indicator":null}}JSON Schema{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https:///www.unai.com/schemas/unit_test_schema.json","type":"object","properties":{"case_id":{"type":"string","title":"Case Id"},"humidity":{"type":"number","title":"Humidity"},"wind_speed":{"type":"number","title":"Wind Speed"},"cloud_cover":{"type":"number","title":"Cloud Cover"},"last_checks":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","title":"Date"},"checked_by":{"type":"string","title":"Checked By"}},"required":["date","checked_by"]},"title":"Last Checks"},"temperature":{"type":"number","title":"Temperature"},"precipitation":{"type":"number","title":"Precipitation"},"sensor_status":{"type":"object","properties":{"wind_sensor":{"type":"string","title":"Wind Sensor"},"cloud_reader":{"type":"string","title":"Cloud Reader"},"rain_indicator":{"type":"string","title":"Rain Indicator"}},"title":"Sensor Status"},"pending_checks":{"type":"array","items":{"type":"string"},"title":"Pending Checks"}}}Testing RulesRules should be tested usingdoctest.Example of these tests can be found in theKitchen Sink example.Generating DocumentationDocumentation for the rules can be generated using theruleau-docscommand.The usage is as follows:ruleau-docs [--output-dir=<argument>] filenameFor example for a file of rules calledrules.pyrun:ruleau-docs rules.pyBuilding & Testing the LibraryPre-requisitesPython 3.9+Package requirements installed by running:pipinstall-rrequirements-dev.txtRunning the TestsTo run all unit tests in the project use the following command:pytest