Home
User-Extended App is a DHIS2 Web Application part of EyeSeeTea's DHIS2 Suite that provides a quick, easy and integrated way to perform common operations to DHIS2 users.
-
Landing page: Displays a table of users with key information such as the userRoles, userGroups, Organization Units Capture and Organization Units Output that the user is a part of. Some fields in the list can be sorted (by clicking on the column header) and a single user or multiple users can be selected using the checkboxes. You can also filter by name, role, groups, organisation units, and see only the users whom you have managing permission over. The table layout (which columns are visible) is user-configurable.
-
Show details: Behaves as the regular show details in any DHIS2 instance. It shows a right side panel with some information about the user. This is also the action by default when clicking a row.
-
Copy in User: Implemented for single selection, it allows for a user to selectively copy over its userRoles, userGroups, OUCapture and OUOutput to one or multiple users. It also has the option of choosing a merge or replace update strategy.
-
Assign to organisation units capture: Implemented for single and multiple selections, it allows setting Data capture and maintenance organisation units capture.
-
Assign to organisation units output: Implemented for single and multiple selections, it allows setting Data output and analysis organisation units.
-
Assign roles: Implemented for single and multiple selections, you can assign roles to one or several users.
-
Assign to groups: Implemented for single and multiple selections, you can assign user groups to one or several users.
-
Edit: Shortcut to regular DHIS2 user management app.
-
Disable/Enable: Disable or enable users in single or multiple selections.
-
Remove: Implemented for single and multiple selections, you can remove users.
-
Replicate users: Implemented for single mode only, you can create multiple users using a user as template. Currently two modes are available: 'From Template' and 'From Table'.
-
Export: Exports and downloads the table of users to a CSV file.
-
Import: Imports a CSV file of users.
In single mode, it works as the regular DHIS2 vanilla feature. For multiple selections, the changes can be saved using one of two strategies: merge or replace. The merge strategy will add the selected values to the current ones each user has, no values will be removed. Replace, on the other hand, overrides any previous values and keeps only those selected in this dialog.
EyeSeeTea (EST) is a Spanish technological consulting company. EST's main mission is to make technology useful for human development through science and non-profit organizations. The EST staff is composed of engineers and computer scientists with a wide array of experience in biological science, telecommunications and cooperation for development.
This application has been funded by the the Norwegian Refugee Council (NRC), the WHO Global Malaria Programme, Samaritan’s Purse and Medecins Sans Frontières (MSF) to support countries in strengthening the collection and use of health data by using DHIS2.
The WHO Integrated Data Platform (WIDP), where several WHO departments and units share a dedicated hosting and maintenance provided by EyeSeeTea, back some specific new features. The Long Term Agreement EyeSeeTea holds with WHO for this maintenance includes the maintenance of this application, ensuring that this application will always work at least with the last version of WIDP.
You can also support our work through a one-time contribution or becoming a regular github sponsor.
This application has been specifically developed for DHIS2 versions 2.35-2.38.
A list of the existing releases can be found at https://github.com/EyeSeeTea/user-app-blessed/releases.
For each release, you can find a brief description of the changes, improvements and fixes, the source code and a zip file that can be deployed in any DHIS2 Instance.
The Software has been licensed as GPLv3 and the License can be found at https://github.com/EyeSeeTea/user-extended-app-blessed/blob/master/license.txt
The Landing Page displays a list of users with some attribute data. The list allows a selection of fields to be sorted (click the column header) and single/multiple selection of users. You can also filter by name, role, group and organisation unit (capture/output), and see only the users whom you have managing permissions over.
The list of columns that are seen in the user table can be configured by clicking the gear icon "Layout settings" on the top/right table. This will open a modal dialog screen. The settings will be saved in the user’s private DHIS2 storage area.
This feature exports the current filters and visible columns to a CSV or JSON. You can select which users will be exported by filtering by name, role, group, organization unit and output. You can also choose which columns will be exported by filtering out the columns as described in the layout settings section. After applying the user filters, column filters and other sorting features, click on the top/right icon of the header (up and down arrows) then click "Export to CVS" / "Export to JSON". A file containing the filtered users will be downloaded.
You can also choose to export an empty template without any data.
To import a view (with predefined filters and sorting), click on the top/right icon of the header (up and down arrows) and choose "Import"
A browser file-selector will open. Select a CSV file on your computer. An example of a CSV file is:
Username,Password,"First name",Surname,Roles
traore_2,Test123$,Alain,Traore,"Facility tracker"
bombali_2,Test123$,Bombali,District,"M and E Officer"
konan_2,Test123$,Didier,Konan,"M and E Officer, User manager"
donor,Test123$,Donor,User,Superuser
When the CSV file is selected, a dialog containing the data will open:
Users with usernames that already exist in the system will be moved to the top of the table and highlighted. If you are sure you want to update those existing users, enable “Overwrite existing users”; then the row counter will still be highlighted (''INDEX-E''), but you’ll be able to proceed with the import.
Some notes:
Valid columns: Username (or username), Password (or password), Name (or name), First name (or firstName), Surname (or surname), Email (or email), Updated (or lastUpdated), Last login (or lastLogin), Created (or created), Roles (or userRoles), Groups (or userGroups), OUOutput (or organisationUnits), OUCapture (or dataViewOrganisationUnits)
Use "||" as a delimiter for Roles, O_UOutput_ and OUCapture
Required columns: Username, Password, First name, Surname
Username is the field that will be used to identify users (it’s unique and immutable), so you don’t need a ID column in the CSV file to update existing users (it will be ignored).
Password field: new users require a password; existing users may either write a new one or leave the field empty so the old password is kept.
Check the warnings icon (right/top) to see non-fatal errors associated with the contents of the imported CSV
Different context actions can be applied to a user or users depending on the type of selection. The context action for a single user can be triggered by right-clicking on the row or the 3-dots component at the end of a row.
Multiple selection is allowed by clicking on the checkbox at the beginning of the line or by using ''control + left mouse click'' on rows.
A brief description of each of the context actions can be found as follows:
Implemented for single selection, it behaves as the regular ''show details'' in any DHIS2 instance. It shows a right side panel with some information about the user. This is also the action by default so that clicking on any row will show the right side panel.
This feature is implemented for single selection. It allows someone to copy over various features from a user to one or multiple user's. You may choose to copy roles, groups, organisation units capture and organisation units output simultaneously from one user to another using the toggles. You can also choose to copy the attribute values over using the merge or replace update strategy. Merge will add the values that are not included in the child user to the child user’s attribute. Replace will eliminate the child user’s attribute and put all of the parent’s values in its place. The modal screen and example is shown below. The toggle for the update strategy is in the top right and the toggles for the various attributes to copy over are on the bottom left if you scroll down.
Implemented for single and multiple selection. In single mode, it will work as the regular DHIS2 vanilla organisation units assignment. You can find this in the user form, a multi-select panel labeled "Data capture and maintenance organisation units". See DHIS2 Documentation for further information.
If multiple rows are selected, its behavior will be slightly different. First, it will select only those organisation units capture common to all the selected users. Secondly, the changes can be saved using one of two strategies: merge or replace. The merge strategy will add the selected organisation units to the current values each user had, no values will be removed. ''Replace'' on the other hand will override any previous values and keep only those selected in this dialog.
This does the same as the “assign to organisation units capture” action, but setting the field ''Data output and analysis organisation units.
Available for single and multiple selections, this action opens a multi-select dialog to assign one or more user roles to a user or set of users. The merge/replace strategies work the same way as the organisation unit dialogs.
Available for single and multiple selections, this action opens a multi-select dialog to assign one or more user groups to a user or set of users. The merge/replace strategies work the same way as the organisation unit dialogs.
Available for single and multiple selections, this action removes a single user or multiple users.
This action is available only on single selection mode. It opens a new window with a form to update various attributes of a user
This action sets the user’s enabled/disabled status. Available for single and multiple users.
This action is available only on single selection mode. It creates new users with the same profile information, data capture/output organisation units, user roles, user group membership, and dimension restrictions as the original user. The replicate menu opens a sub-menu with two modes:
In this mode you will replicate users and specify:
- The number of users to create (required, max value: 100)
- Username template (required). The special string ''$index'' must be used somewhere in the template so new users have a different username. ''$index'' counter starts at 1.
- Password template (required). You can also use ''$index'', but it’s not compulsory, different users may have the same password. Server-enforced validations apply.
This would create 5 users: ''admin_1/District123_1, admin_2/District123_2, …, admin_5/District123_5''.
In this mode you will create new users and specify:
- Username (required). Must be unique.
- Password (required). Server-enforced validations apply.
- Other optional fields: First name, Surname, Email, Organisation units, Organisation units output. When any of those fields are left blank, it will use values from the original user.
Make sure you have, at least, the following versions of ''node'' and ''npm'':
node version v16.11.10 or higher.
npm version v6.14.15 or higher.
Use the following commands to check your current versions:
node -v
npm -v
Clone the repository from github and checkout the development branch with the following commands:
git clone https://github.com/EyeSeeTea/user-extended-app
git checkout development
Install the dependencies:
npm install
This app uses a special version of d2-ui so you will have to clone this module from github and checkout the ''user-extended-app'' branch, as follows:
git clone [https://github.com/EyeSeeTea/d2-ui.git ''https://github.com/EyeSeeTea/d2-ui.git'']
git checkout user-extended-app
Then you will have to install the dependencies and build the repo:
npm install
npm run build-only
Finally you will have to link the application with the local module using:
npm link // runs inside d2-ui
npm link d2-ui // runs inside user-extended-app
To set up your DHIS2 instance so that it works with the development service, you will need to add the development server’s address to the CORS whitelist. You can do this within the DHIS2 Settings app under the '''Access''' section. Upon selecting the access tab, add ''http://localhost:8081'' -and any other development URL- to the CORS Whitelist.
The starter app will look for a DHIS 2 development instance configuration in ‘$DHIS2_HOME/config’. So for example if your DHIS2_HOME environment variable is set to ~/.dhis2, the starter app will look for /.dhis2/config.js and then ~/.dhis2/config.json and load the first one it can find. If no environment variable is defined or no file can be found, the application will try to load the configuration from the application root folder (typically user-extended-app). Assuming your code is at ~/user-extended-app, the app will try to load ~/user-extended-app/config.js and afterwards ~/user-extended-app/config.json. You can find a template for this file in the root, config.js.template, Rename and modify it with the appropriate parameters.
The config should export an object with the properties baseUrl and authorization, where authorization is the base64-encoding of your username and password. If no config is found, the default baseUrl is http://localhost:8080 and the default username and password is admin and district, respectively. See webpack.config.js for more details.
This should enable you to run the following node commands:
To run the development server:
npm start
If d2-ui has been changed, you will have to rebuild it:
npm run build-only // at d2-ui folder
To check the code style for both the JS and SCSS files, run:
npm run lint
To build the app for production:
cp app-config/app-config-[ORG].json app-config.json
npm build
React is the "view" part of the front-end applications, it has a component based architecture. At DHIS2 we also take advantage of the JSX syntax that is generally used with React.
d2 is the DHIS2 abstraction library that allows you to communicate with the DHIS2 api in a programmatic way. d2-ui is the user-interface component library built on top of d2 to allow reusing common components for DHIS2 applications. d2-ui also contains our own application that wires code through its "stores" and "actions".
d2-ui makes use of material-ui for rendering more basic components like text fields and lists. It is therefore quite useful to look into this library too when building DHIS2 apps and making use of d2-ui.
A feedback button can be found at all times at the bottom of the page. Please use it to report problems or suggestions. When clicked, a pop up dialog will appear and the user can both highlight or hide (private information) relevant areas.
Once all selections are satisfied, you will move to the next screen where a detailed description is provided.
Finally clicking on submit will create an issue in the blessed repository. This issue will contain a screenshot with the highlighted and hidden areas together with the description and some information regarding the user browser, platform, etc. All issues can be found at https://github.com/EyeSeeTea/user-app-blessed/issues
