Configuração DHIS2 para usar o aplicativo Android¶

The DHIS2 Android Capture App is fully metadata-driven. This means that the programs, datasets, forms, user access, and even many user interface elements in the app are determined by how the server is configured. Proper metadata and access configuration on the DHIS2 server will ensure that users see the appropriate functionality based on their assigned roles and organization units.

This section outlines how to prepare your DHIS2 instance for Android use and points to relevant configuration tools and documentation resources. For a complete and successful implementation, please read the detailed and updated documentation to get all the information about configuring the DHIS 2 Server for using with the DHIS 2 Android Capture App.

User Setup¶

To ensure the Android Capture App functions properly for field users, it’s important to prepare not only the metadata but also user roles, access scopes, and program configuration. This section walks through the essential steps to configure users and control what they see and do in the app.

Android users need access to the app through valid credentials and assigned roles. An Android-compatible user should have a dedicated user role, assigned organisation units, and access to at least one program or dataset.

DHIS2 does not require a special user type for Android access — standard users can authenticate, as long as they have been granted the correct authorities and metadata is shared with them appropriately.

Note

To simplify setup in large deployments, consider defining user groups for Android users, and assigning roles and sharing access via those groups.

1. Creating User Roles¶

Antes de criar um usuário, primeiro você precisa definir uma função de usuário DHIS 2. O DHIS 2 Android Capture App não requer nenhuma das autoridades encapsuladas em uma função de usuário. A segurança para um programa DHIS 2 ou conjunto de dados é definida como programa ou acesso a dados do conjunto de dados.

Para fins de depuração da web com seus usuários, é recomendável criar e atribuir uma função de usuário com a funcionalidade de captura de dados, que deve incluir:

• Aplicativo de captura de rastreamento, aplicativo de captura de eventos e / ou aplicativo de entrada de dados
• Painel (para poder fazer login)
• Limpador de cache (você precisará limpar o cache)

Keep roles simple and task-specific. Avoid assigning global admin rights unless necessary, and test the role on a staging server before rollout.

Note

When users enter a TEI and while it is not synced to the server they will be able to delete the TEI and the enrollment even if they have not been asigned the specific authorities. This is by design and to allow users rolling back in case of having entered wrong data (TEI and/or enrollment) and thus preventing it reaching the server and requiring another user with higher privileges to fix the issue.

2. Create user¶

Em segundo lugar, você deve criar um usuário, para o qual precisará adicionar alguns detalhes básicos, como o nome do usuário e atribuir a função a ele.

• Nome de usuário: name.android
• Exemplo: belen.android
• Atribuição de função do usuário: atribua à função que você criou na etapa um.

3. Assign Organisation units¶

A terceira etapa é atribuir as unidades organizacionais ao usuário que você acabou de criar.

Existem três tipos de atribuição de unidade organizacional:

• Data capture: Datasets and well as program creation of TEI, Enrollments and Events. Data pre-downloaded in the app at first login will be the one belonging to these org units.
  • Mobile users are not expected to access the org. unit hierarchy of a whole country. Maximum number of org units is difficult to set,as the App does not set the limit, but the resources on the device (memory, processor). We could say below 250 org units should be safe, but still believe that is a very big number for a mobile use case.
• ** Saída de dados: ** para análise de dados. Não aplicável no Android.
• Search Org. Units: Expands TEI search (when online) across further Org Units. Individual records can be downloaded for offline use.
  • When configuring search org. units, make sure that your capture org. units are contained in your search org.units, to do that capture org. units have to be selected as well as search org. units.

Configuração visual: compreender o que é renderizado e por quê¶

Form layout¶

The DHIS2 Android Capture App renders data entry screens based on the structure of the assigned programs and datasets. Each program stage (event) or data set is displayed as a form, and the layout of that form can include sections if they are defined in the metadata. The app does not support custom HTML forms, but it fully supports section-based layouts and program rules (tracker and event programs) for dynamic behavior.

Customizations - Colors and Icons¶

The Android Capture App supports extensive visual customization through the use of icons and colors. These elements improve usability by allowing program and form elements to be visually distinguished and quickly recognized.

Administrators can assign icons and colors to a variety of metadata objects, including programs, program stages, tracked entity types, datasets, data elements, attributes, and option sets. These icons appear throughout the app — in the home screen, data entry forms, dashboards, and filters — to improve navigation and comprehension.

Built-in and Custom Icons¶

There is an icon library of over four hundred images in DHIS2 instances. As of recent versions, administrators can also upload their own custom icons (e.g., .png or .jpeg) directly via DHIS2. While this increases flexibility, it introduces tradeoffs such as larger metadata payloads and potential sync delays.

For performance reasons, it's recommended to keep custom icons small in size (under 50KB) and only use them where they add clear value (e.g., custom campaign branding or highly specific visual codes).

Metadata Assignments

The following metadata types support color and icon assignment in Android: * Tracked Entity Types * Programs and Program Stages * Conjunto de dados * Data Elements and Attributes * Indicators and Program Indicators * Option Sets and Options

Rendering Modes for Sections¶

For program stages with sections, Android supports three rendering modes that determine how the fields or options within a section are visually arranged for the user:

• Listing: elements are shown as a flat list.

• Sequential: typically means that fields or options are displayed one after another in a vertical list, guiding the user through the form step by step.

• Matrix: arranges fields or options in a grid or table-like format, allowing for a more compact and comparative view, which can be useful for data that is best visualized in rows and columns.

These can be configured in the program stage settings using the mobile rendering type field. Implementers should choose the rendering mode that best matches the complexity and flow of their form, balancing clarity and data entry speed.

A System Administrator can decide the best way to render the information in each program stage section by setting up the mobile rendering type, as shown on the screenshot.

Advanced Behavior Configuration via Android Settings¶

In addition to form layout and visuals, the Android Settings Web App (ASWA) allows you to control how the app behaves across different contexts and user roles. These settings can be tailored to align with field realities, user capacity, and program complexity. Implementers are encouraged to review these options and apply them based on the specific needs of their workflows.

Some of the most impactful configurable features include:

• Sync limits and frequency: Define how much data (TEIs, events, datasets) is synced and how often, ensuring performance in bandwidth-limited environments.

• Map accuracy thresholds: Control the GPS precision required before capturing coordinates — critical for use cases like mobile outreach, campaign site mapping, or logistics.

• Enable/disable specific actions: Restrict features like referrals, manual geo-location, or dashboard widgets, reducing clutter or enforcing SOPs.

• Expand/collapse form sections: Improves navigation, especially in long, sectioned forms. Users can focus on one section at a time, minimizing errors.

• Quick actions in dashboards: Enable shortcuts for common activities like event creation or TEI navigation directly from the dashboard.

• Filters: Predefine the filters to be displayed across the app.

• Local analytics: Allow users to view indicators, charts, or summaries based on the data available on their device, supporting feedback and decision-making in disconnected settings.

For more details, see the Android Settings Configuration Guide.

Program Rules & Indicators¶

Setting Up Program Rules¶

Program rules allow you to embed real-time logic into the Android app, even while offline. They automatically enforce data validation, default values, conditional display, and other dynamic behaviors, greatly improving data quality and user experience.

Key considerations:

• Rule context and priority: Each rule is defined for a specific program (and optionally a stage), and is executed in ascending order of assigned priority. This ensures deterministic behavior, especially when rules depend on the output of other rules.
• Use of variables and expressions: You can base rules on attribute or data element values, as well as built-in variables like eventDate, orgUnit, or relative date functions. Be sure to define any custom variables you reference.

Note

We recommend to test the Android App in parallel with the configuration of your program rules, this is to make sure that your changes in the server are properly reflected and working in the app.

Steps to configure a program rule

1. Define the context and priority for the execution of the rule.

1. Write the program rule expression. Variables have to be defined by the administrator to be able to evaluate information entered for a TEI attribute or a program stage data element.

1. Define the action or actions to be executed when the program rule expression is true

When setting up your program rules you should be aware of what is supported by the DHIS 2 Android app. You can check the updated list in the user guide.

Definição de indicadores e legendas do programa¶

Program indicators are used in the Android Capture App to display real-time calculations based on values in a program event or data set. These indicators help users interpret the data they're collecting by surfacing meaningful summaries.

To display a program indicator (events or tracker) in the Android app, ensure the “Display in form” option is enabled in the indicator configuration.

To display indicators in data sets, ensure you assign them during the data set configuration in the maintenance app.

• Using Legends for Visual Feedback *

Legend sets allow you to apply colors to numeric ranges, making it easy to visually flag critical values such as:

• Risk thresholds
• Stock levels
• Survey scores

Legends are supported in the following areas in Android:

• Program Indicators (in Tracker and Event programs)
• Data Elements (in Event programs and Datasets)

You can create legend sets in Maintenance > Other > Legends in the DHIS2 server and then assign them either to a program indicator or to a data element. In the app, legends appear as background color changes or status indicators inside the form, giving users immediate visual cues.

You can check the updated information of what is supported when using program indicators in the user guide.

IDs reservados¶

In many Tracker programs, a unique identifier — such as a case ID, patient number, or voucher code — must be generated when a new Tracked Entity Instance (TEI) is registered. DHIS2 supports this using Generated Values for Tracked Entity Attributes (TEAs), which follow predefined patterns (e.g. ANC-#####) managed by the server.

Because field users often work offline, the Android app handles this by preloading a pool of reserved IDs, downloaded from the server during sync. These are then assigned locally, even without connectivity.

The number of IDs reserved per tracked entity type is configurable through the Android Settings Web App (ASWA). This setting is crucial for ensuring smooth operation in low-connectivity environments. If ASWA is not configured, the default number of reserved IDs is 100.

Sempre que o usuário usa um valor (registra uma instância de entidade rastreada), o aplicativo irá:

1. Verifique se há valores restantes suficientes e reabasteça quando necessário (se menos de 50 valores estiverem disponíveis).
2. Atribua o primeiro valor disponível à instância de entidade rastreada e remova-o da lista de valores disponíveis.

Sempre que o aplicativo for sincronizado, ele irá:

1. Exclua os valores reservados expirados.
2. Verifique se há valores restantes suficientes e reabasteça quando necessário (se menos de 50 valores estiverem disponíveis).

Um valor é considerado "expirado" quando uma das seguintes condições for verdadeira:

• "expiryDate" está vencido. Por padrão, o servidor define o período de expiração para 2 meses.
• If the attribute pattern is dependent on time, i.e., it contains the segment `CURRENT_DATE(format)`, the app calculates an extra expiry date based on that pattern.

Caution

When using auto-generated unique values which contain dates as part of the pattern the expiryDate of those values will be linked to that date pattern which might result in unexpected behavior if the pattern is not defined well.

Example: The value UniqueID has been configured with a pattern like CURRENT_DATE(MM)-SEQUENTIAL(###) and today is 31^st of January, the application would download 100 values (from 01-001 to 01-101) to allow the application working offline and having enough values, but tomorrow, 1^st of February, the applicataion would not have any available values as all would have been marked as expired and so it would display such message.

No App, o usuário também pode verificar os valores disponíveis e recarregá-los no menu de configurações.

Quando o aplicativo fica sem valores e o servidor não pode fornecer mais, o usuário receberá uma mensagem no formulário de entrada de dados dizendo que não há mais valores disponíveis. Você deve consertar isso no lado do servidor.