Data Dimension Disabler Tool
Admin tool of the week: this post is part of a weekly series featuring small, open-source maintenance tools from the HISP Centre for DHIS2 system administrators.
The problem
Categories, organisation unit group sets, data element group sets and category option group sets can be enabled as data dimensions. This makes them available for disaggregation in Data Visualizer, Maps and Line Listing. It is easy to switch on, so over the years many instances end up with dozens of enabled dimensions.
Every enabled dimension adds a column to the analytics tables, whether anyone uses it for analysis or not. That costs time on every analytics run and disk space on the server. We have seen up 20% reduced analytics runtimes in some instance after disabling unused categories. It also clutters the dimension lists that users scroll through in the analytics apps. But nobody wants to disable a dimension without knowing whether it will break someone’s charts or reports, so they stay enabled.
What the tool does
Data Dimension Disabler Tool lists every enabled data dimension and ranks it by actual use:
- Favorites: how many saved visualizations, maps and event visualizations use the dimension. The Manage view button can split this into public, shared and private favorites.
- Views: how many times those favorites were opened in the last 12 months.
- % of dimension views: the dimension’s share of all views of favorites that use a dimension.
- Data set reports: for categories, how many data set reports show sub-totals for it. Hover the number to see which data sets.
Dimensions with no favorites, no views and no data set reports are good candidates for disabling, and you can disable them directly from the table. The other columns help with the cases in between. For example, “HIV age” in the Sierra Leone demo has no favorites and no views, but the TB/HIV (VCCT) monthly summary report still uses it for sub-totals.
The first time you open the tool, it asks to install an SQL view (“Data dimension usage”) that it uses to count favorites and views. Nothing is installed without asking, and you can remove the view again from the tool.
Try it on the demo instance
You can try the tool without installing anything: open implement.im.dhis2.org/tools/apps/tool-data-dimension-disabler and log in as tools / District1#. The demo is a copy of the Sierra Leone database with some usage history added.
Use with care
Disabling a dimension is quick to undo, but it does have consequences:
- Favorites that use a disabled dimension stop working until it is re-enabled and analytics re-generated.
- Data set reports show empty sub-totals for a disabled category. The confirmation dialog lists the affected data sets.
- The analytics tables only shrink at the next analytics run.
The tool asks for confirmation every time. You can re-enable any dimension in the Metadata Management app (Data dimension checkbox). As always, try it on a test instance first.
Get it
- Supported DHIS2 versions: 2.40, 2.41, 2.42 and 2.43
- Download: tool-data-dimension-disabler-1.1.0.zip, then install it in the App Management app (Upload app)
- Documentation and source: github.com/dhis2-utils/tool-data-dimension-disabler
- Authorities: Add/Update SQL view to install the view, and metadata write on the dimensions you want to disable
- Already using an older version? Version 1.1.0 is installed as a separate app: the older “Data Dimension Disabler” (1.0.0) or “Category dimension disabler”. Uninstall the old one after installing this one; the existing SQL view is updated in place. If users without the ALL authority use the tool, add the new app to their user roles.
Questions, bugs or ideas? Reply below.
Click here to receive notifications for #admin-tool-weekly topics: 