Data Integrity Actions

[jbee]

Introduction

This proposal details an extension of the YAML file based data integrity checks to enable checks to not just find issues but also offer solutions to fix them.

Use cases

Issues found by data integrity can be roughly classified in 3 categories:

• fix all: the problem is clear and a known fix can be applied to all occurrences using a SQL update statement of sorts. In the UI this is one action button any the authority required to use it is declared by the check. example: remove trailing white-space
• fix individually: the problem is clear and a known fix exists but there is potential for false positives so individual user confirmation is required. Each issue has a button to run the action which calls API based in a template declared in the check. The authority depends on the called API. example: delete duplicate (only one of them would be deleted but user needs to decide which one)
• it depends: the right fix depends on the context, more information is needed. sometimes this clearly goes beyond that can be handled within data integrity. Other times there may be a fix number of possible actions which can be determined looking at limited extra information that the check result can provide as well. The UI would show 2 or more buttons with different actions as well as additional text information to support the decision making. The buttons each call API endpoints similar to above case.

Proposal

Add a actions map to the check information that outlines the details of "generic" actions that are available for the found issues.
They are generic in the sense that they connect the check details output of an issue to a API call based on fixed schema for an action.

An Action object has the following properties:

• method: the HTTP method to use to make the API call
• url: the URL template to use for the API call; it might contain placeholders
  • (none): the action affects all issues at once (bulk)
  • {id}: is replaced with the Issue's id property
  • {refs.id}: is replaced with the comma separated list of the Issue's refsobjectsid` field (new)
• body (optional): a JSON body to send with the API call (mostly used for patch)
• confirm (optional): If present a confirmation dialog showing this text should be displayed to inform the user of alternatives or consequences of the chosen action.

The UI isn't aware what actions entail or how they work. All actions are handled the same.
The UI only has to inspect the url to look for the presence or absence of placeholders to decide if individual issue buttons
and checkboxes are available or not.

UI

The issues should be rendered as a list or table.
In this example there are 2 issues, each having a delete and an edit button, one has a comment for context.
The checkboxes can be used to bulk delete the selected entries.

• All [delete all selected]
• Name1 [delete] [edit] (comment1)
• Name2 [delete] [edit]

For another check there might only be one bulk action which no template placeholders.
Therefore no checkboxes can be supported. The action always affects all entries.

• All [delete all]
• Name1 (comment1)
• Name2 (comment2)

Example

A actions map that has 2 actions, delete and edit:

{ 
  // existing properties of a check
  "actions": {
    "delete": { 
      "method": "DELETE", 
      "url": "/api/categoryOptions/{id}", 
      "confirm": "Another solution would be to use the option with a category (edit). Really delete the category option?" 
    },
    "edit": {
      "method": "GET", 
      "url": "/dhis-web-maintenance/index.html#/edit/categorySection/categoryOption/{id}", 
    }
  }
}

Analysis

See https://github.com/dhis2/dhis2-core/wiki/Component-%E2%80%90-Data-Integrity-Checks#usage-analysis-for-actions