From 5f1067ca474068877ec235ceb635e2481fbf8d4f Mon Sep 17 00:00:00 2001 From: Thijs Coenen <458483+tcoenen@users.noreply.github.com> Date: Thu, 24 Nov 2022 12:51:51 +0100 Subject: [PATCH 1/3] Document re-evaluation of routing rules on signal updates --- docs/README.md | 1 + docs/topics/routing-rules.md | 73 ++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 docs/topics/routing-rules.md diff --git a/docs/README.md b/docs/README.md index 32c30f117..afd132e85 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,3 +8,4 @@ * [Technical roadmap](topics/technical-roadmap.md) * [Dummy data for local development or testing](topics/dummy-data.md) * [Open Source dependencies](topics/dependencies.md) +* [Routing expressions](topics/routing-rules.md) diff --git a/docs/topics/routing-rules.md b/docs/topics/routing-rules.md new file mode 100644 index 000000000..1fe5ad074 --- /dev/null +++ b/docs/topics/routing-rules.md @@ -0,0 +1,73 @@ +# Routing rules +The backoffice part of the Signalen application allows users to set up rules +that will take nuisance complaints and assign to them a department +and/or user. These rules are called "routing expressions" in Signalen and they +can be edited in the Django admin. These expressions allow reasoning based on +nuisance complaint location, status, and category. + +The routing expressions will be invoked at the creation of a nuisance complaint +and if the correct feature flag is set, also on change of location and category. + + +## Running routing rules on creation of a nuisance complaint +When a complaint is created using the Signalen frontend, machine learning will +assign it a probable main and sub category and based on that category the +reporter will be shown some extra questions. The main and sub category may not +be enough information to determine who or which department should start work on +the complaint. + +To fill this gap routing expressions were added to Signalen, these are used to +assign nuisance complainta to the correct department and possibly user. Routing +rules can take into account not just the main and sub catagories, but also the +location and time of the reported nuisance. Rules are given an priority and +executed one-by-one until a routing expression matches. At that time the +nuisance complaint is assigned and the matching stops. + + +## Running routing rules on updates to a nuisance complaint +Running the routing expressions only at the creation may lead to a assigned user +or department being inappropriate after updates to the complaint. It is possible +to run the routing expressions again after certain updates to the nuisance +complaint. The Signalen installation must be configured with the feature flag +... set to True. With that feature flag activated Signalen will re-evaluate the +routing expressions and possibly re-assign the nuisance complaint. + +Because routing expressions act on only a subset of nuisance complaint +properties, only updates to those properties will cause a re-evaluation of the +routing expressions. In practice this means that updates to location and +category will trigger re-evaluation. As before, the routing expressions run +one-by-one and in the same order as before, stopping at the first match. + +Caveat: because all rules are evaluated in order, it may be that, for instance, +a location update triggers a rule re-evaluation but the matching rule may not +use the location at all. The order in which the rules are evaluated is fixed but +can be controlled by setting the `order` property of the routing rules. + + +## Example of possible surprising behavior +Take the situation where we have two routing expressions. On that +assigns a complaint to department "Stadsdeelwerken" with the expression +``` +sub == "Zwerf Aval" +`` +and one that assign a complaint to "j.janssen@example.com" of +"CEN (Stadsdeel Centrum)" with the expression: +``` +location in area."stadsdeel"."centrum" +``` +Further assume that the sub category matching rule is always evaluated first +because of the way the rules are configured. + +Given a complaint in sub category "Zwerf Afval" where a location update puts it +in borough (stadsdeel) Centrum, the location rule will not match because it is +still superseded by sub category rule. The nuisance complaint will still be +assigned to "Stadsdeelwerken" based on its sub category. That the trigger to +re-evaluate was a location update changes nothing to that fact. + + +## Glossary + +| English | Dutch | In code | +| ------------------ | ------- | -------- | +| nuisance complaint | melding | signal | +| reporter | melder | reporter | From fd350439fecc5d3988a8da596cc792a1494d29a4 Mon Sep 17 00:00:00 2001 From: Thijs Coenen <458483+tcoenen@users.noreply.github.com> Date: Thu, 24 Nov 2022 14:40:39 +0100 Subject: [PATCH 2/3] Rephrase the caveat about rule order based on review input. --- docs/topics/routing-rules.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/topics/routing-rules.md b/docs/topics/routing-rules.md index 1fe5ad074..0996a3fe3 100644 --- a/docs/topics/routing-rules.md +++ b/docs/topics/routing-rules.md @@ -1,5 +1,5 @@ # Routing rules -The backoffice part of the Signalen application allows users to set up rules +The backend part of the Signalen application allows users to set up rules that will take nuisance complaints and assign to them a department and/or user. These rules are called "routing expressions" in Signalen and they can be edited in the Django admin. These expressions allow reasoning based on @@ -40,8 +40,15 @@ one-by-one and in the same order as before, stopping at the first match. Caveat: because all rules are evaluated in order, it may be that, for instance, a location update triggers a rule re-evaluation but the matching rule may not -use the location at all. The order in which the rules are evaluated is fixed but -can be controlled by setting the `order` property of the routing rules. +use the location at all (see example in the next section). This, quite possibly, +surprising behavior is not apparent on creation of a nuisance complaint because +at that time all of the complaint's properties are set at once. + +The only way that the order of evaluation can be changed is by adding or +removing rules, or by setting their `order` property. Routing expressions can +only be managed through the Django Admin pages. On those pages it is possible +for application administrators to create, delete, or edit routing expressions +including changing the `order` property. ## Example of possible surprising behavior @@ -62,12 +69,13 @@ Given a complaint in sub category "Zwerf Afval" where a location update puts it in borough (stadsdeel) Centrum, the location rule will not match because it is still superseded by sub category rule. The nuisance complaint will still be assigned to "Stadsdeelwerken" based on its sub category. That the trigger to -re-evaluate was a location update changes nothing to that fact. +re-evaluate was a location update, changes nothing to that fact. ## Glossary -| English | Dutch | In code | -| ------------------ | ------- | -------- | -| nuisance complaint | melding | signal | -| reporter | melder | reporter | +| English | Dutch | In code | +| ------------------------- | --------------------- | -------- | +| nuisance complaint | melding | signal | +| reporter | melder | reporter | +| application administrator | functioneel beheerder | | \ No newline at end of file From d4e8cc01b254a73922ec1d577064400e42d4a8e7 Mon Sep 17 00:00:00 2001 From: Thijs Coenen <458483+tcoenen@users.noreply.github.com> Date: Sat, 26 Nov 2022 10:32:45 +0100 Subject: [PATCH 3/3] Add DSL_RUN_ROUTING_EXPRESSIONS_ON_UPDATES feature flag name in routing docs --- docs/topics/routing-rules.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/topics/routing-rules.md b/docs/topics/routing-rules.md index 0996a3fe3..089720051 100644 --- a/docs/topics/routing-rules.md +++ b/docs/topics/routing-rules.md @@ -29,8 +29,9 @@ Running the routing expressions only at the creation may lead to a assigned user or department being inappropriate after updates to the complaint. It is possible to run the routing expressions again after certain updates to the nuisance complaint. The Signalen installation must be configured with the feature flag -... set to True. With that feature flag activated Signalen will re-evaluate the -routing expressions and possibly re-assign the nuisance complaint. +`DSL_RUN_ROUTING_EXPRESSIONS_ON_UPDATES` set to True. With that feature flag +activated Signalen will re-evaluate the routing expressions and possibly +re-assign the nuisance complaint on updates. Because routing expressions act on only a subset of nuisance complaint properties, only updates to those properties will cause a re-evaluation of the @@ -56,7 +57,7 @@ Take the situation where we have two routing expressions. On that assigns a complaint to department "Stadsdeelwerken" with the expression ``` sub == "Zwerf Aval" -`` +``` and one that assign a complaint to "j.janssen@example.com" of "CEN (Stadsdeel Centrum)" with the expression: ```