Dish

Dish is a command line tool for interaction with the DHIS 2 Web API. It aims at simplifying common tasks and is suitable for handling batch metadata operations, system maintenance operations and more.

Installation

Dish is a NPM package and requires nodejs and NPM to be installed on your local system. You can install Dish with:

The "-g" global option will ensure that you can invoke the available Dish commands anywhere on your command line.

Configuration

Dish is configured through a dish.json configuration file which must be a valid JSON object. Note that the protocol (e.g. http://) is mandatory for the base URL. Example configuration:

Note that the baseurl should contain the hostname and the context path but not the api part. Examples of base urls are "https://play.dhis2.org/demo" and "http://localhost:8080".

This configuration file will be searched for at a location defined by a DHIS2_HOME environment variable (borrowed from the DHIS 2 setup). If not found, your home directory will be searched. Place the dish.json file in the desired directory.

Command overview

The available commands are listed in the table below. Details about each command follow below.

Command | Description --- | --- dish_remove_objects | Removes metadata objects dish_remove_org_units | Removes organisation units including data values dish_post_tracked_entity_instances | Imports tracked entity instances including attributes dish_enroll_tracked_entity_instances | Enrolls tracked entity instances into programs for org units dish_post_events | Imports single events including data values dish_post_custom_form | Uploads a custom data entry form for a data set dish_post_js | Uploads a javascript file dish_post_css | Uploads a CSS file dish_post_metadata | Imports a JSON metadata document dish_gen_analytics_tables | Initiates an update of analytics tables dish_gen_resource_tables | Initiates an update of resource tables dish_run_integrity_checks | Runs SQL view-based integrity checks dish_set_system_setting | Sets a system setting value dish_get_resources | Fetches web resources from a list of requests

Available commands

The following commands are available.

Remove metadata objects

The dish_remove_objects command will remove metadata objects (identifiable objects). It reads identifiers (UIDs) from a CSV file. It requires that the authenticated DHIS 2 user has the authority to delete objects.

Parameter | Description --- | --- file | CSV file with organisation units object-type | Type of object to delete, matching the Web API plural URL path, e.g. dataElements, categoryOptions

The CSV file must have a column header name with the value "id", and contain one identifier (UID) per row.

Example CSV file:

Remove organisation units

The dish_remove_org_units command will remove a batch of organisation units, including associated complete data set registrations, data approvals and data values. It reads organisation units from a CSV file. It requires that the authenticated DHIS 2 user has the "ALL" authority in order to delete data values and at least the "delete organisation units" authority in order to delete organisation units.

Parameter | Description --- | --- file | CSV file with organisation units

The CSV file format allows the following column names: "name", "id" and "code". The command will attempt to match on any specified column/property. Column names are case-sensitive. You must specify at least one column.

Example CSV file:

Import tracked entity instances

The dish_post_tracked_entity_instances command will import a batch of tracked entity instances, including tracked entity, organisation unit and attributes. It reads input from a CSV file.

Parameter | Description --- | --- file | CSV file with tracked entity instances output-file | (Optional) Write summary of import operation to a file with the given name payload-file | (Optional) Write payload to import to a file with the given name

The CSV file format allows for the following column names: "trackedEntity", "orgUnit", and UIDs for tracked entity attributes. The "trackedEntity" column refers to the UID of the tracked entity, the "orgUnit" column refers to the UID of the organisation unit and the attribute columns may contain corresponding attribute values.

Example CSV file:

Enroll tracked entity instances

The dish_enroll_tracked_entity_instances command will enroll a batch of tracked entity instances into programs for organisatio units. It reads input from a CSV file.

Parameter | Description --- | --- file | CSV file with tracked entity instance enrollments output-file | (Optional) Write summary of import operation to a file with the given name payload-file | (Optional) Write payload to import to a file with the given name

The CSV file format allows for the following column names: "trackedEntityInstance", "orgUnit", "program", "enrollmentDate", "incidentDate", which refers to UIDs and dates respectively.

Example CSV file:

Import events

The dish_post_events command will import a batch of single events including data values.

Parameter | Description --- | --- file | CSV file with events output-file | (Optional) Write summary of import operation to a file with the given name payload-file | (Optional) Write payload to import to a file with the given name org-unit-id-scheme | (Optional) uid or code data-element-id-scheme | (Optional) uid or code id-scheme | (Optional) uid or code

The CSV file format allows for the following column names: "program", "orgUnit", "eventDate", "status", "storedBy", "longitude", "latitude"; following these, UIDs for any number of data elements may be specified.

Example CSV file:

Upload custom data entry form

The dish_post_custom_form command will upload a custom HTML data entry form from a file for a given data set.

Parameter | Description --- | --- dataset | Identifier of data set for which to create form file | Custom form HTML file

Upload custom Javascript

The dish_post_js command will upload a custom Javascript file using the files/script Web API resource.

Parameter | Description --- | --- file | Javascript file

Upload custom CSS

The dish_post_css command will upload a custom CSS file using the files/style Web API resource.

Parameter | Description --- | --- file | CSS file

Import metadata

The dish_post_metadata command will upload a JSON metadata file using the metadata Web API resource.

Parameter | Description --- | --- file | JSON file

Generate analytics tables

The dish_gen_analytics_tables command will initiate the analytics table generation process.

Parameter | Options | Description --- | --- | --- skip-resource-tables | false or true | Skip generating resource tables skip-aggregate | false or true | Skip generating aggregate analytics tables skip-events | false or true | Skip generating event analytics tables

Generate resource tables

The dish_gen_resource_tables command will initiate the resource table generation process.

Run integrity checks

The dish_run_integrity_checks command will run integrity checks through the remote API. Integrity checks are SQL views with names prefixed with "INTEGRITY_". The integrity SQL views should return rows which illustrate integrity violations. The SQL views checks should return zero rows if the integrity is valid. It is recommended to provide a description for the SQL views explaining the nature of the integrity violation.

Set system setting

The dish_set_system_setting command will set a value for a system setting.

Parameter | Description --- | --- setting | Name of system setting value | Value

Get resources

The dish_get_resources command will fetch arbitrary web resources based on a list of requests from the specified file. This is useful to stress-test API resources.

Parameter | Description --- | --- file | Text file with requests

The text file should contain the requests to be fetched. The file should contain one line per request and use context path URLs (not including the base URL specified in the configuration).

Example text file:

Build from source

Follow these steps to build this tool from source:

• Install node and git
• Clone this repo with git clone
• Install module with npm install -g