7. Creating workgroups

The correct setup of Keycloak workgroups is a prerequisite for the HERA application to work properly. The main steps are described below. For more details on how to create workgroups in Keycloak, please refer to the official Keycloak documentation.

Step 1 - Creating two main workgroups

Create two main workgroups (first level). Give the first main workgroup the name “do” (which stands for “district office”) and the second one “po” (which stands for “province office”).

Step 2 - Creating all DOHA workgroups

Under the main “do” workgroup, all possible province-district combinations must be defined. These are called the DOHA workgroups.

Important: this must be done both in English and in your local language.

A DOHA workgroup is created as follows:

1. Within the “do” main workgroup, create a nested group representing the province (e.g. “bokeo” ). This is the first nested level.

2. Within the province group (e.g. “bokeo” ), create another nested group representing the district (e.g. “huoixai” ). This is the second nested level.

3. Within the district group (e.g. “huoixai”), create a group representing the workgroups used by HERA. This is the third nested level.

The rules for creating such groups at the third level of a DOHA workgroup are as follows:

Each workgroup must have the prefix do_. This prefix is always in the English language.

Each workgroup must have either the suffix _registrar or _clerk suffix. This reflects the role of the user. The HERA application logic determines to which workgroup a specific declaration or registration is assigned. Both suffixes should be present in the configuration of workgroups for a specific province and district combination. These suffixes are always in the English language.

When a province or district consists of multiple words, these words must be separated by a dash (e.g. do_vientiane-capital_chanthabuly_registrar).

The various levels in a DOHA workgroup are summarized in the diagram shown below:

Step 3 - Creating all POHA workgroups

Under the main “po” workgroup, all possible province values must be defined. These “province office” workgroups are used by Province Office users. POHA workgroups should reflect all possible province values. Important: this must be done both in English and in your local language. A POHA workgroup is created as follows:

1.Within the “po” main workgroup, create a nested group representing the province (e.g. “bokeo”). This is the first nested level.

The rules for creating such groups at the second level of a POHA workgroup are as follows:

Each workgroup must have the prefix po_. This prefix is always in the English language.

Each workgroup must have either the suffix _registrar or _clerk suffix. This reflects the role of the user. The HERA application logic determines to which workgroup a specific declaration or registration is assigned. Both suffixes should be present in the configuration of workgroups for a specific province. These suffixes are always in the English language.

The format of the workgroup has to be do_$province-name$_$role$, where _$province-name$ can be either in English or in the language of the country where HERA has been installed.

When a province consists of multiple words, these words must be separated by a dash (e.g.“po_vientiane-capital_clerk”).

The various levels in a POHA workgroup are summarized in the diagram shown below:

Step 4 - Adding a user to a DOHA or POHA workgroup

Each user can either be a DOHA or POHA user, but not both. This means that a user either belongs to a DOHA workgoup OR to a POHA workgroup. Belonging to both workgroup types at the same time is not allowed.

Important: a DOHA user must be added to the English DOHA workgroup AND to the translated DOHA workgroup. A POHA user must be added to the English POHA workgroup AND to the translated POHA workgroup.

Please refer to the Keycloak documentation for more information on how to add users to a group.