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:

npm install dish2 -g

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:

{
  "dhis": {
    "baseurl": "http://localhost:8080/dhis",
    "username": "admin",
    "password": "district"
  }
}

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.

export DHIS2_HOME='/home/dhis/config'
touch /home/dhis/config/dish.json

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

dish_remove_objects --file <path-to-csv-file> --object-type <object-type-name>

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

Example CSV file:

"id"
"Fzj5GhvP91x"
"CpdYVRMm6gI"
"r3s85EzShLE"

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

dish_remove_org_units --file <path-to-org-unit-csv-file>

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:

"name","code"
"Johns clinic", "Fac021"
"Bobs dispensary", "Fac015"
"St Martas hospital","Fac042"

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

dish_post_tracked_entity_instances --file <path-to-tei-csv-file> --output-file <path-to-output-file>

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:

"trackedEntity","orgUnit","QZO9afZwgtb","CkPE4ap6k6y","YpkMB1YsgyS"
"ahvFNubg3F5","v29iD7vYdpE","10196410140911","11","agfield"
"ahvFNubg3F6","v29iD7vYdpE","10196410140073","54","agfield"
"ahvFNubg3F7","v29iD7vYdpE","10196410140072","68","agfield"

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

dish_enroll_tracked_entity_instances --file <path-to-csv-file> --output-file <path-to-output-file>

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:

"trackedEntityInstance","orgUnit","program","enrollmentDate","incidentDate"
"bIoemewGh6f","v29iD7vYdpE","aCNTXoZ0Tmj","2015-01-01","2015-01-06"
"SILtFfe34kj","v29iD7vYdpE"",aCNTXoZ0Tmj,"2015-01-04","2015-01-07"
"cDnzs9C3Msg","v29iD7vYdpE","aCNTXoZ0Tmj,"2015-01-02","2015-01-09"

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

dish_post_events --file <path-to-event-csv-file> --output-file <path-to-output-file>

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

Example CSV file:

"program","orgUnit","eventDate","storedBy","longitude","latitude","qrur9Dvnyt5","oZg33kd9taw"
"eBAyeGv0exc","DiszpKrYNg8","2013-05-17","admin","10.9","59.8","22","Male"
"eBAyeGv0exc","DiszpKrYNg8","2013-05-17","admin","11.3","55.1","22","Female"
"eBAyeGv0exc","DiszpKrYNg8","2013-05-17","admin","10.3","54.3","22","Male"

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

dish_post_custom_form --dataset <dataset-id> --file <path-to-custom-form-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

dish_post_js --file <path-to-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

dish_post_css --file <path-to-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

dish_post_metadata --file <path-to-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
skip-enrollment	false or true	Skip generating enrollment anaylytics tables

dish_gen_analytics_tables

dish_gen_analytics_tables --skip-aggregate true

Generate resource tables

The dish_gen_resource_tables command will initiate the resource table generation process.

dish_gen_resource_tables

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.

dish_run_integrity_checks

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

dish_set_system_setting --setting keyEmailPort --value 587

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

dish_get_resources --file <path-to-text-file>

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:

/api/analytics.json?dimension=dx:SA7WeFZnUci;V37YqbqpEhV&dimension=pe:THIS_YEAR
/api/analytics.json?dimension=dx:rbkr8PL0rwM;ybzlGLjWwnK&dimension=pe:LAST_YEAR
/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201401&orgUnit=DiszpKrYNg8

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