Skip to content

Advanced customization (Extension)

Create project-specific dataset, event program, and tracker program forms in src/extensions/. Then commit your changes and create installation packages for testing and release.

iCapture v3 is a React and JavaScript application for DHIS2. Before starting, review the Architecture Overview to understand the shared core and project extension model.

Start here

  1. Read Fork the Core Repository.
  2. Follow Start iCapture v3 Locally to connect your fork to your DHIS2 instance.
  3. Read Extension Basics, and use Core Reference to find reusable stores, components, and helpers.
  4. Choose Create an Aggregate Form, Create an Event Form, or Create a Tracker Form.
  5. Complete Testing and Troubleshooting before sharing your project.
  6. Follow Conventional Commits and Commitizen, then create a local test ZIP or a versioned release.

Choose your form type

Form type Use it for Guide
Aggregate Values collected for a dataset, organisation unit, period, and applicable category dimensions Create an Aggregate Form
Event Individual events and their data fields in an event program Create an Event Form
Tracker Tracked entity attributes, enrollment, and program stage events Create a Tracker Form

Start with one small form. Confirm that it loads, saves, and restores saved values before adding advanced behaviour.

How the repositories work

The iCapture team maintains the original icapture-v3 repository. You receive read access and create a fork named icapture-v3-your_project_name in your own GitHub account or organisation. You develop your project's forms in that fork, inside src/extensions/.

Setup and reference

You need Where to find it
Forking the core repository Fork the Core Repository
Local environment and DHIS2 connection Start Locally
Extension files and form registration Extension Basics
Stores, shared functions, and configuration Core Reference
Reusable inputs, selectors, and UI controls Component Catalog
Form examples and metadata packages Aggregate, event, and tracker guides
Validation and troubleshooting Testing and Troubleshooting
Commits and versioning Conventional Commits and Commitizen
Local installation package Create a Local Installation ZIP
Published releases Versioning and Releases

The guides use src/extensions/ relative to the application repository root. Replace example account names, connection settings, and metadata identifiers with the values for your project where instructed.

Maintenance agreement

  • The iCapture team maintains core code and documents changes to extension interfaces.
  • Project teams own their custom forms and project-specific configuration.
  • Project teams use documented extension interfaces and keep customisation in the designated extension location wherever supported.
  • Any required changes outside that location must be documented and reviewed during core updates.
  • Project teams verify each update before using it in their deployed application.