3 Simple Steps to Import Organisation Units into DHIS2 Fast

Quickly import organisation units into DHIS2 using CSV files — best practices for efficient data management included

Photo by Paolo Candelo on Unsplash

One morning, one of my managers informed me that I would be part of a new DHIS2 project. He told me to contact the project manager to gather the system design requirements. When I met with the project manager, she explained that we needed to create over 3,517 Organisation units which included; provinces, districts, and facilities. However, the DHIS2 system I would be working on was brand new and had only 20 Organisation units set up. This means without a more efficient approach, I would manually have to add thousands of Organisation units which would be time-consuming.

Fortunately, there is a quicker and more efficient way for importing multiple Organisation units in DHIS2 at once. This bulk upload method saves time and reduces the number of errors that can occur.

This article will focus on importing Organisation units into DHIS2 using CSV files step by step. Whether this is the first time setting up a new DHIS2 instance or updating existing metadata, this method will improve accuracy and scalability.

Whether this is the first time setting up a new DHIS2 instance or updating existing metadata, this method will improve accuracy and scalability.

If you prefer a visual explanation, you can watch the full demonstration below:

[embed]How to Add Multiple Organisation Units in DHIS2 Using CSV

Starting line — Get Setup

If you are familiar with Excel or any other software application, platforms, and programming languages you should know about the Comma-separated values (CSV) text file. CSV is a tabular format that stores data in a table structure, using commas to separate values.

In the *DHIS2 Documentation, there is the Develop* section which contains details about the development of the DHIS2 software. To navigate through the documentation and find your way to the Metadata section, follow the steps below:

1. Open the *DHIS2 Documentation*
2. Click *Explore developer documentation and click the Using the API drop-down (top left corner) to find the [Metadata](https://docs.dhis2.org/en/develop/using-the-api/dhis-core-version-241/metadata.html)*.

The GIF below demonstrates the steps to locate the Metadata section in the DHIS2 Documentation:

DHIS2 Documentation — Metadata

In the Metadata section, the *Organisation units *subsection specifies how the CSV file should be structured. Follow the steps below to look at the CSV file header format:

1. Scroll down on the Table of contents (top right corner) to find *CSV metadata import.*
2. In the CSV metadata subsection, click *Organisation units* to see the format.

The images below illustrate what should be contained in the CSV file:

Organisation Unit CSV Format

As seen from the images above, the header should contain all the variables listed in the column section. The name field is the only field required in the CSV file for the import process to be successful.

The code block below shows all the header names that should be included in the CSV file.

name, uid, code, parent, Short name, Description, Opening date, 
Closed date, Comment, Feature type, Coordinates, URL, Contact person, 
Address, Email, Phone number

If you would like to follow along with me as I build the CSV file, you can view and download the file from Google Sheets here.

Header format

With all this being said, you are ready and set, so let’s get going!!

Step 1 — Get the Organisation Unit Id

If we consider Zambia as our context, the country can be broken down into provinces and districts. In DHIS2, this would be represented as Zambia being the parent Organisation unit, with Central, Copperbelt, Eastern, Lusaka, Northwestern, Southern, and Western Provinces as its children.

NB: The Provinces list is missing Muchinga, Luapula, and Northern Province because the DHIS2 instance did not contain all the 10 provinces.

Zambia/
├── Central Province
├── Copperbelt Province
├── Eastern Province
├── Lusaka Province
├── Northwestern Province
├── Southern Province
└── Western Province

If Northern Province were to be added under Zambia, it is important to note Zambia’s identification (parent id). In this case, the parent id can be found in the *Maintenance app under the Organisation unit*.

The GIF below demonstrates the steps required to find the Maintenance app the DHIS2:

Locate the Maintenance Application

The Maintenance app will have a list of sections that form the DHIS2 instance. The GIF below shows all the sections and where to find the Organisation unit section in DHIS2:

Selecting Organisation Unit

Once you select the Organisation unit, you will see the hierarchy from the parent (Zambia) to the children’s Organisation units (Central, Copperbelt, Eastern Lusaka Province, etc.).

To find the parent id, follow the steps below:

1. Click the action icon, which brings a list of features.
2. Click Show details to find the id which can be copied from there.

The GIF below highlights the Organisation units currently in DHIS2 and how to find the Organisation unit id:

Find the parent id

Step 2 — Get the CSV Import File

With the parent id, you can now add it to the Google Sheet file which contains the Organisation Unit header format. The minimum requirement for creating an Organisation unit CSV Import file is as follows:

• Add the name of the Organisation unit. In the example below, the name is Northern Province
• Add the parent id to the parent field. In the example below, the parent field is XWz5H96vp4
• Add the Opening date which should be back-dated to when data collection started. If there is no opening date, entering data will not be possible. The date format is year-month-day (2000–01–01).

The GIF below is a demonstration of how to add the name, parent, and Opening date in the Organisation unit CSV Import file in Excel:

Creating the CSV Import File

After completing the creation of the CSV Import file, Save your file as a CSV (Comma delimited) (.csv) *as shown in the GIF below:

Saving the file as CSV (Comma delimited) (.csv)*

Step 3 — Go Upload the CSV Import file

When it comes to importing the CSV Import file, make sure to log in to the DHIS2 instance where the Organisation units need to be created. Then follow these steps:

1. Open the Apps Menu (9-box grid in the top right corner).
2. Select “Import/Export” from the list of apps.
3. In the Import/Export app, navigate to “Metadata Import”.
4. Click “Upload File” and select your CSV Import file.
5. Choose “CSV” as the format.
6. Check “First row is a header” to ensure correct column mapping.
7. Under “Class Key”, select “Organisation Unit”.
8. Click “Start Dry Run” to test for errors.
9. If the Dry Run is successful, scroll down and click “Start Import” to finalize.

The GIF below breaks down all the steps needed to import the CSV Import file:

Organisation Unit CSV Import

Review the Organisation unit structure within the Maintenance app to ensure it looks like the image below:

Organisation unit structure

Further Considerations

Adding More Organisation Units at Once

If there was a need to add several districts under the Northern Province, repeat the process by:

• **Identifying the parent id* as shown in Step 1 (Get the Organisation Unit Id)*. In this instance, the parent is not Zambia but Northern Province as shown in the image below:

Northern Province id

• Creating the Organisation unit CSV Import file as shown in Step 2 (Get the CSV Import File). The only addition is to replicate the parent id across all the Organisation unit names.

The before and after images below show the addition of the Organisation units, and then the addition of the parent id replicated in each field:

The before image shows the addition of the districts and the after image shows the parent id the districts fall under

Include an opening date and make sure that the date format is year-month-day (2000–01–01) as shown in the image below.

Adding the Opening date to each Organisation unit

Make sure to Save the CSV Import file as shown in the GIF below.

Saving the file as CSV (Comma delimited) (.csv)*

• Import the CSV file into the DHIS2 instance as shown in Step 3 (Go Upload the CSV file) and in the GIF below:

Importing multiple Organisation Units

Review the Work

At this point, we are done with our assignment to import the Organisation unit(s). To ensure all the districts have been added to the DHIS2 instance, go to the Organisation unit section in the Metadata app.

The GIF below illustrates all the Organisation units that have been included under Zambia and Northern Province:

Organisation Units that have been imported

Common Errors and How to Fix Them

Suppose you added multiple Organisation units (Chinsali District, Isoka District, Kanchibiya District, Lavushi Manda District, and others) to your DHIS2 instance and now want to use the same CSV file to create another Organisation unit (Kasama District) under a different parent id (Zambia). A problem may occur if the previously added Organisation Units are not properly deleted and the file is not saved separately.

The Wrong Approach

Here are the steps to delete the rows in the wrong way:

1. Select the cells in the worksheet.
2. Click “delete” from your keyboard to remove the data.
3. *Enter the Organisation unit* name, parent id, and Opening date.

The GIF below demonstrates the wrong way of deleting the Organisation units:

Deleting data in Excel the wrong way

Take note that in this example, the name of the CSV Import file will be named org_unit_kasama_example as shown in the image below:

The File name and format

If you attempt to import the CSV Import file and initiate a Dry run, you will get the error below:

Import Summary message - Errors

These errors occur because right-clicking and pressing “Delete” on the data (without deleting the actual rows) may still leave the data recoverable in some cases. Here’s why:

• If you just clear the cells (e.g., pressing “Delete” on the keyboard or using “Clear Contents”), the data isn’t fully removed. The data becomes invisible but is still recoverable with Undo (Ctrl + Z) or some forensic tools such as *Autopsy, [FTK Imager](https://www.exterro.com/), [EnCase Forensic](https://www.opentext.com/products/forensic)*, etc.
• If you right-click and choose “Delete” (without deleting entire rows), Excel shifts the remaining data up or left, but traces of the old data can still exist in the file history or temporary memory.

The solution to dealing with these errors is to delete the rows entirely. This changes the structure of the file, making data recovery more difficult (though not impossible).

The Right Approach

Here are the steps to delete the rows entirely:

1. Select all rows containing the data.
2. Navigate to the “Delete” tab on the ribbon and click “Delete” or “Delete Sheet Rows”.
3. Re-enter the necessary data, including the* Organisation unit name, Parent ID, and Opening Date.*
4. Save the file as a CSV to ensure the changes are applied.

Deleting data in Excel the right way

The process for importing remains the same as stated above in the CSV Import file section. The upload process should not generate any errors, as shown in the GIF below:

Import Summary message - Completed

Final Thoughts

The job is done! This CSV import method makes a huge difference. What would have been a tedious two-week endeavor is now a swift two-day operation. Give it a try and experience the time savings yourself. Don’t hesitate to reach out with any questions.

The biggest takeaway today? You can create multiple Organisation Unit files in just 3 quick steps, maximizing productivity and simplifying complex tasks. It’s that simple.

If you found this article valuable, I’d love for you to follow me on Medium and subscribe or connect with me on LinkedIn.

Also, drop a comment to share your thoughts, experience, or any challenges you’ve faced.

And if you know someone who might benefit from this, feel free to share it with them!

The contents of external submissions are not necessarily reflective of the opinions or work of Maven Analytics or any of its team members.

We believe in fostering lifelong learning and our intent is to provide a platform for the data community to share their work and seek feedback from the Maven Analytics data fam.

*Submit your own writing here if you’d like to become a contributor.*

Happy learning!

-Team Maven