Changes between Version 1 and Version 2 of S3/S3Anonymize

Timestamp:

04/03/18 18:32:37 (8 years ago)

Author:

Dominic König

Comment:

--

S3/S3Anonymize

@@ -1 +1 @@
 = S3Anonymize =
 [[TOC]]
+
+S3Anonymize is a tool to remove sensitive information from a record (and related records) based on configurable rules.
+
+== Overview ==
+
+S3Anonymize removes information from a record (and related records) based on rules. It is primarily intended for person data, but can be re-used for any type of record.
+
+== Configuring Rules ==
+
+Rules are configured using {{{s3db.configure}}} for the target table. The rules format looks like this:
+
+{{{#!py
+s3db.configure("pr_person",
+               anonymize = {# A name and title for the rule set:
+                            "name": "default",
+                            "title": "Names, IDs, Reference Numbers, Contact Information, Addresses",
+
+                            # Rules how to clean up fields in the master record:
+                            "fields": {"first_name": ("set", "-"),      # Set field to this value
+                                       "last_name": ("set", "-"),
+                                       "pe_label": anonymous_id,        # Callable returning a new field value
+                                       "date_of_birth": obscure_dob,
+                                       "comments": "remove",            # Set field value to None
+                                       },
+
+                            # Rules for related records:
+                            "cascade": [("dvr_case", {"key": "person_id",               # Foreign key in the related table
+                                                      "match": "id",                    # Match this key of the parent table
+
+                                                      # Field rules for the related table
+                                                      "fields": {"comments": "remove",
+                                                                 },
+                                                      }),
+
+                                        ("pr_contact", {"key": "pe_id",
+                                                        "match": "pe_id",
+                                                        "fields": {"contact_description": "remove",
+                                                                   "value": ("set", ""),
+                                                                   "comments": "remove",
+                                                                   },
+
+                                                        "delete": True,                 # Delete the related records after cleanup (default False)
+                                                        }),
+                                        ],
+                            },
+              )
+}}}
+
+ - in cascading rules, the {{{key}}}+{{{match}}} properties can be replaced by a {{{lookup}}} property to configure a callable with the signature {{{lookup(table, rows, tablename)}}} that returns a set of relevant record IDs in the related table
+
+ - standard field rules are:
+   - {{{"remove"}}} sets the field value to None
+   - {{{"reset"}}} sets the field value to the field default
+   - {{{("set", value)}}} sets the field value to the specified value
+ - field rules can also be callables with the signature {{{rule(master_id, field, current_value)}}} that return the new value for the field
+ - field rules must produce valid records (i.e. the resulting value must pass database constraints and validators)
+ - after applying field rules, S3Anonymize will execute {{{update_super}}} and {{{onaccept}}} like any other CRUD method
+ - records in related tables will additionally be deleted if {{{"delete": True}}} is specified (which makes sense if the field rules remove all useful information from those records anyway)
+ - if cascading records are to be deleted, this will ''additionally'' execute {{{ondelete}}} (as last step)
+
+Instead of a single set of rules, it is possible to configure multiple rule sets as list:
+{{{
+s3db.configure("pr_person",
+               anonymize = [{...first rule set...}, {...second rule set...}],
+               )
+}}}
+
+...each with its own {{{name}}} and {{{title}}}. These rule sets will later be selectable in the GUI, so that the user can choose to only remove some, but not other data from the record (see screenshot below).
+
+== GUI and REST Method ==
+
+=== S3AnonymizeWidget ===
+
+To embed S3Anonymize in the GUI, it comes with a special widget class S3AnonymizeWidget and a UI script (s3.ui.anonymize.js).
+
+S3AnonymizeWidget produces an action button/link (with a hidden dialog) that can be embedded in the record view (e.g. in postp in place of the delete-button):
+{{{
+def postp(r, output):
+
+    if r.record and not r.component and r.method in (None, "update", "read") and isinstance(output, dict):
+
+        buttons = output.get("buttons") or {}
+
+        from s3 import S3AnonymizeWidget
+        buttons["delete_btn"] = S3AnonymizeWidget.widget(r, _class="action-btn anonymize-btn")
+
+        output["buttons"] = buttons
+
+    return output
+}}}
+
+The {{{_class}}} parameter can be used to control the appearance of the link. The {{{widget}}} function will automatically embed the UI dialog and script, and authorize the link.
+
+Clicking on the link brings up a dialog like this:
+
+
+== Back-end Function ==