DHIS2 Users

Access user information, permissions, and organizational access from DHIS2.

Prerequisites: Client setup from dhis2 skill (assumes dhis is initialized)

Overview

The user endpoints provide:

• Current authenticated user information (/api/me)
• User listing and search (/api/users)
• User groups and memberships (/api/userGroups)
• Organization unit access scope

Get Current User Info

def get_current_user(dhis, fields: str = "*") -> dict:
    """Get information about the authenticated user."""
    return dhis.api.get("me", params={"fields": fields})

# Basic info
user = get_current_user(dhis)
print(f"Username: {user.get('username')}")
print(f"Name: {user.get('displayName')}")
print(f"Email: {user.get('email')}")

# With specific fields
user = get_current_user(dhis, fields="id,username,displayName,email,organisationUnits[id,name]")

Get User's Organization Units

def get_user_org_units(dhis) -> dict:
    """Get org units the current user has access to."""
    user = dhis.api.get(
        "me",
        params={
            "fields": "organisationUnits[id,name,level],dataViewOrganisationUnits[id,name,level],teiSearchOrganisationUnits[id,name,level]"
        }
    )

    return {
        "data_capture": user.get("organisationUnits", []),
        "data_view": user.get("dataViewOrganisationUnits", []),
        "tei_search": user.get("teiSearchOrganisationUnits", [])
    }

# Usage
org_units = get_user_org_units(dhis)
print(f"Can capture data at: {len(org_units['data_capture'])} org units")
print(f"Can view data at: {len(org_units['data_view'])} org units")

Get User Authorities (Permissions)

def get_user_authorities(dhis) -> list:
    """Get authorities/permissions for current user."""
    user = dhis.api.get("me", params={"fields": "authorities"})
    return user.get("authorities", [])

def check_user_authority(dhis, authority: str) -> bool:
    """Check if user has a specific authority."""
    authorities = get_user_authorities(dhis)
    return authority in authorities or "ALL" in authorities

# Usage
authorities = get_user_authorities(dhis)
print(f"User has {len(authorities)} authorities")

# Check specific permission
if check_user_authority(dhis, "F_EXPORT_DATA"):
    print("User can export data")

Common Authorities

Authority	Description
ALL	Superuser - all permissions
F_EXPORT_DATA	Export data values
F_VIEW_UNAPPROVED_DATA	View unapproved data
F_APPROVE_DATA	Approve data
F_TRACKED_ENTITY_INSTANCE_SEARCH	Search tracked entities
F_METADATA_EXPORT	Export metadata

List Users

def get_users(dhis, query: str = None, org_unit: str = None, page_size: int = 50) -> list:
    """Get list of users with optional filtering."""
    params = {
        "fields": "id,username,displayName,email,lastLogin,disabled,organisationUnits[id,name]",
        "pageSize": page_size
    }

    if query:
        params["query"] = query
    if org_unit:
        params["ou"] = org_unit

    all_users = []
    page = 1

    while True:
        params["page"] = page
        response = dhis.api.get("users", params=params)

        users = response.get("users", [])
        if not users:
            break

        all_users.extend(users)

        if len(users) < page_size:
            break
        page += 1

    return all_users

# Get all users
users = get_users(dhis)

# Search users
users = get_users(dhis, query="john")

# Users in specific org unit
users = get_users(dhis, org_unit="ImspTQPwCqd")

Get User Groups

def get_user_groups(dhis, fields: str = "id,name,displayName,users::size") -> list:
    """Get all user groups."""
    response = dhis.api.get(
        "userGroups",
        params={"fields": fields, "paging": "false"}
    )
    return response.get("userGroups", [])

def get_user_group_members(dhis, group_id: str) -> list:
    """Get members of a user group."""
    response = dhis.api.get(
        f"userGroups/{group_id}",
        params={"fields": "users[id,username,displayName,email]"}
    )
    return response.get("users", [])

# List all groups
groups = get_user_groups(dhis)
for group in groups:
    print(f"{group['name']}: {group.get('users', 0)} members")

# Get group members
members = get_user_group_members(dhis, "wl5cDMuUhmF")

Get Current User's Groups

def get_my_user_groups(dhis) -> list:
    """Get user groups the current user belongs to."""
    user = dhis.api.get("me", params={"fields": "userGroups[id,name,displayName]"})
    return user.get("userGroups", [])

# Usage
my_groups = get_my_user_groups(dhis)
print(f"Member of {len(my_groups)} groups:")
for group in my_groups:
    print(f"  - {group['name']}")

Check Data Access Scope

def get_data_access_scope(dhis) -> dict:
    """Analyze the current user's data access scope."""
    user = dhis.api.get(
        "me",
        params={
            "fields": "id,username,organisationUnits[id,name,level,path],dataViewOrganisationUnits[id,name,level,path],userRoles[id,name],authorities"
        }
    )

    capture_ous = user.get("organisationUnits", [])
    view_ous = user.get("dataViewOrganisationUnits", [])

    # Determine lowest level accessible
    capture_levels = [ou.get("level", 0) for ou in capture_ous]
    view_levels = [ou.get("level", 0) for ou in view_ous]

    return {
        "username": user.get("username"),
        "data_capture_org_units": len(capture_ous),
        "data_view_org_units": len(view_ous),
        "capture_level_range": (min(capture_levels) if capture_levels else None,
                                max(capture_levels) if capture_levels else None),
        "view_level_range": (min(view_levels) if view_levels else None,
                            max(view_levels) if view_levels else None),
        "user_roles": [r.get("name") for r in user.get("userRoles", [])],
        "is_superuser": "ALL" in user.get("authorities", [])
    }

# Usage
scope = get_data_access_scope(dhis)
print(f"User: {scope['username']}")
print(f"Superuser: {scope['is_superuser']}")
print(f"Can capture data at {scope['data_capture_org_units']} org units")

Get User Activity

def get_user_activity(dhis, user_id: str = None) -> dict:
    """Get user's last login and activity info."""
    if user_id:
        user = dhis.api.get(f"users/{user_id}", params={"fields": "id,username,lastLogin,created"})
    else:
        user = dhis.api.get("me", params={"fields": "id,username,lastLogin,created"})

    return {
        "username": user.get("username"),
        "last_login": user.get("lastLogin"),
        "created": user.get("created")
    }

Users Report (DataFrame)

import pandas as pd

def users_to_df(users: list) -> pd.DataFrame:
    """Convert users list to DataFrame."""
    rows = []
    for user in users:
        rows.append({
            "id": user.get("id"),
            "username": user.get("username"),
            "displayName": user.get("displayName"),
            "email": user.get("email"),
            "lastLogin": user.get("lastLogin"),
            "disabled": user.get("disabled", False),
            "orgUnits": len(user.get("organisationUnits", []))
        })
    return pd.DataFrame(rows)

# Generate user report
users = get_users(dhis)
df = users_to_df(users)
print(f"Total users: {len(df)}")
print(f"Active users: {len(df[~df['disabled']])}")
print(f"Users never logged in: {len(df[df['lastLogin'].isna()])}")

Use Cases

Scenario	Endpoint/Function
Check my permissions	get_user_authorities()
What data can I see	get_user_org_units()
List all users	get_users()
Find inactive users	users_to_df() + filter
Audit user access	get_data_access_scope()
Check group membership	get_my_user_groups()