A. How it works

What HDS-Explorer is made of, and the path a form takes from a household to the register.

The examples are Arba Minch HDSS: site code am, the supervisor sv01 Hana Bekele and the field worker fw01 Alemu Tesfaye, both working in the subvillages Muja and Boko.

A.1 The parts

The tablets never change the register themselves. They send forms; the server checks each one and only then changes the register.

A.2 The register

The register is the site's record of its people:

• Regions: the site's areas, from the largest down. Arba Minch uses Country › Region › District › Village › Subvillage. Field workers work in subvillages.
• Locations: the houses inside a subvillage.
• Households: the people living together in a location.
• Members: every person ever registered, with their stays in households (residencies), their relationship to the head, their marriages and pregnancies.

After the first census a person enters the register only by birth or by moving in, and leaves only by death or by moving out.

A.3 Rounds

A round is one pass of visits over the whole site. Round 0 is the baseline: the first census, where every household and person is registered. Every later round is an update round: the field worker visits each household again and records what happened since the last visit.

A visit is one call at one household in one round. Every form is collected inside a visit.

Rounds are created on the console (chapter D, Rounds).

A.4 The forms and the release pack

The standard forms arrive on a new server in one file, the release pack (release-pack-standard-2.zip). It holds three kinds of form:

The pack is imported once, during site setup (chapter B, Site setup). Chapter F, Forms, covers later packs and the site's own forms.

A.5 The path a form takes

Depending on When data is uploaded in Settings › System, steps 3 and 4 happen by themselves as forms arrive, or when a data manager runs Validate & execute. A data manager can return a form to its collector with a note, or exclude it; the tablet shows this on Sync uploads (chapter C, The tablet). Chapter E, Daily data, covers the console side.

HDS-Explorer 1.0.0 build 7.

B. Site setup

The first steps after installation. They turn the empty server into the server of one site: its name, code and calendar, the standard forms, its areas and its team. Do them in this order, on the console, signed in as admin / Hdsx-admin-1.

The example is Arba Minch HDSS, with the area levels and names of its OpenHDS server. Type your own site's values where the example has Arba Minch's.

B.1 Site name, code and calendar

Settings › System, tab General.

1. Under This site:
   • Site name: Arba Minch HDSS.
   • Site code: am. 2 to 16 lower-case letters and digits, starting with a letter.
2. Under Language and calendar, System input calendar: Ethiopian calendar (the default) or Gregorian calendar. The console shows and takes every date in this calendar.
3. Leave the rest as it is. Save.

The page says "Default settings were updated." The badge at the top of every page changes from Site · no code to Site · am.

B.2 Import the release pack

The standard forms come in the release pack. A new server has no forms until it is imported.

1. Download release-pack-standard-2.zip onto the computer you use the console from (the installation chapters may already have done this).
2. Forms › Release packs, box Import a release pack.
3. Release pack (.zip): choose release-pack-standard-2.zip. Review.
4. The review lists every form in the pack and what importing does to it. On a new server each one says New form. Nothing is written yet.
5. Under Import this pack, Import.

The box Imported packs lists the pack. Verify (top right) checks every imported form against its pack: "No mismatch in N versions".

The pack brings the core events (Household Registration, Visit, Member Enumeration, Birth, Death, migrations, pregnancy, corrections), the core observations (SES, Verbal Autopsy) and the add-on modules (Morbidity, Immunization, HPV, Family Planning, NCD, Mental Health, Food Insecurity, Poverty).

If the import is refused with "This site's server has no site code", go back to B.1.

B.3 Choose the add-ons

Every add-on in the pack starts enabled. For each add-on the site does not collect:

1. Forms › Forms, open the add-on (for example Family Planning).
2. Edit. Under Availability, untick Enabled. Save.

The form's page shows Disabled. The core events and core observations are always collected.

B.4 Name the region levels

Settings › Region levels.

Name each level the site uses, from the largest down, with no gap. Use the levels of the site's OpenHDS server, so both systems describe the area the same way.

Typing a name ticks Enabled by itself. Do not click Enabled after typing: unticking it clears that level's name and every level below it.

Save. The page says "The area levels were saved."

Houses are not a level: a house is a location inside a region of the lowest level. Field workers create locations on the tablet.

B.5 Create the regions

Population › Regions › New region, once per region, from the top level down: the Level list only offers a level whose level above already has a region.

1. Level. Then choose the region above it at each level as the boxes appear.
2. Name. The Code fills in by itself from the name, a moment after you leave the box.
3. Modules: tick DSS Surveillance.
4. Save.

For Arba Minch:

The code is made from the first letters of the name; when those are taken, the next free combination. It can differ from the code in OpenHDS (there Gamo Gofa is GAG).

B.6 Create the accounts

The roles

Every server has these six roles. Each account has one.

Settings › Permissions shows which role may open which page.

Only a supervisor, a data manager or an administrator can set up a tablet. A field worker signs in on a tablet a supervisor has set up (chapter C, The tablet).

The accounts

Settings › Users › New user, once per person.

1. First name, Last name, Username and Password. Leave Must change password unticked.
2. Roles: tick one.
3. Modules: leave empty. The user gets the default module, DSS Surveillance.
4. Areas: tick the person's subvillages. Only regions of the lowest level are offered.
   • A field worker with no area ticked sees every area on the tablet.
   • A supervisor with no area ticked sees no records.
5. Save. The account gets a code made from the initials, for example AT1.

The starting team:

Give the supervisor and the field workers of an area the same subvillages: the tablet the supervisor sets up receives the accounts of the field workers who share an area with them (while Share area accounts with tablets is on in Settings › System, the default).

B.7 Write the tablet files

The tablets download files the server writes: settings, forms, regions, accounts, households. The server rewrites them by itself after most changes; write them all once now.

Tablets › Tablet export › Execute all.

Every job shows Finished.

B.8 Check

Next: chapter C, The tablet.

Tested with HDS-Explorer 1.0.0 build 7 and release pack standard-2.

C. The tablet

Installs the app, has the supervisor set the tablet up, signs in the field worker, and then goes through a day's work: a visit, a form, the upload, and what the server sends back.

Chapter B, Site setup, must be done, with the supervisor sv01 / Hdsx-sv01-1 and the field worker fw01 / Hdsx-fw01-1, both with Muja and Boko.

A supervisor sets up every tablet. Field workers cannot download the tablet's data themselves; they sign in on a tablet the supervisor has set up.

C.1 Install the app

The tablets use the local build of the app: its name on the tablet ends in local.

1. On the tablet, open the link in the browser and download the file.
2. Open it. The first time, Android asks to allow installing apps from this source: allow it for the browser, then Install.

After this first install the app updates itself: at a sync it offers Update available when the server has a newer app.

C.2 Set up the tablet (the supervisor)

Open the app. The first screen is Set up this device.

1. Server URL: delete the address in the box and type the site's server:

   http://<server address>:8081/hds-explorer-server
   

   The same address as the console's, starting with http://. 2. Username sv01, Password Hdsx-sv01-1. Connect. 3. The next screen, Setting up this device, lists what the tablet downloads. Synchronize all. 4. Each part goes to 100%. The tablet says Device set up: "The device is set up for its area. Each person now signs in with their own account." OK.

The tablet keeps the address. To change it later: Change Settings on the sign-in screen.

C.3 The field worker signs in

The sign-in screen says Sign in to continue.

1. Username fw01, Password Hdsx-fw01-1. Login.
2. Choose your working area: the areas above the field worker's own are already chosen. Choose the village and the subvillage: Kolla Shara, Muja. Then Use Muja · N households.

Home opens.

Signing in works without network. A password changed on the console reaches the tablet at the next download.

C.4 A visit

A visit is one call at one household in one round. Every form is collected inside a visit. A round must exist on the console (chapter D, Rounds).

An existing household

1. Home › Household. The households of the working area are listed, each marked Not visited, Visited or Visit not possible for the current round.
2. Tap the household. Create visit.
3. Select respondent: tap the person who answers. Or Respondent from another household, or The visit is not possible.
4. The visit form opens. Fill it in and Save.

The visit screen opens, with the tabs People and Reminders.

A new household

1. Home › Household › New household. Add new Household.
2. The Location Registration form opens for the house. Fill it in, including Get GPS Location, and Save.
3. The Household Registration form, then the visit form. Save each.
4. On the visit screen, tap the household, then Member enumeration: register the head first. Then every other resident.
5. The tablet asks Choose the respondent.

C.5 Fill a form

On the visit screen, tap the household or a person. Their list of forms opens. Tap a form.

1. Answer each page, Next.
2. After the last page, the review list shows every answer. Tap a row to go back to it.
3. Save.

A saved form waits on the tablet for the upload. A draft is never uploaded: complete it first.

When every form of the household is collected: Finish visit. The tablet refuses to finish while something required is missing, and says what. Finishing a visit does not upload it.

Records already saved can be found again in Home › Collected forms, in the tabs Visited households, Core forms and Add-on forms.

C.6 Upload

At the end of the day, with network:

1. Home › Sync. Synchronization opens. A field worker sees only Sync uploads.
2. Select all.
3. Upload selected forms. The tablet says "Upload finished".
4. Upload details shows "Core forms: N uploaded, N with errors" and "Questionnaires: N accepted, N rejected, N still to send". OK.

Without network the tablet says Can't connect. Nothing is lost; upload later.

What the upload screen shows

Each time Sync uploads opens with network, the tablet asks the server what became of the forms it sent earlier, so a row can change days after its upload.

After the run the tablet may also say "N uploaded earlier refused by the server since the last sync": those rows now show Rejected or Returned.

A record the data manager returned

The data manager returns a record when something in it is wrong and only the field worker can fix it (chapter E, Daily data).

1. Home › Sync, Sync uploads. The row shows Returned.
2. Tap its details button. Returned by the data manager, then Note from the data manager with the note, and "Open it, correct what the note asks (the IDs cannot be changed) and send it again."
3. Home › Collected forms, tab Core forms (or Add-on forms for a questionnaire). Tap the record. It opens on the review list.
4. Edit. The form starts again from the first page. The IDs are read-only.
5. Correct what the note asks. Save.
6. Home › Sync, Sync uploads: the record is under Not uploaded. Tick it, Upload selected forms.

A record collected on another tablet says "This record was collected on another tablet and cannot be opened on this one." Correct it on that tablet.

C.7 Download (the supervisor)

New forms, settings, households from other tablets and the register's changes reach a tablet only by a download. The supervisor does it:

1. Sign in as sv01 / Hdsx-sv01-1. Home › Sync.
2. Sync uploads: upload everything first. A download is refused while the tablet holds a form the server has not accepted: Upload your data first.
3. Sync downloads, Synchronize all.

The records on the tablet are kept when a download fails; Synchronize all again.

C.8 Check

Tested with the tablet app 1.0.0 build 4-local against HDS-Explorer 1.0.0 build 7.

D. Rounds

A round is one pass over every household of the site's area. The first is the baseline, round 0: every house, household and person is recorded once. Every later round is an update round: each household is visited again and only what changed is recorded.

Release: HDS-Explorer 1.0.0 build 7, tablet app 1.0.0 build 4-local.

The example is Arba Minch, subvillage Muja, with the data manager dm01 (password Hdsx-dm01-1), the supervisor sv01 (Hdsx-sv01-1) and the field worker fw01 (Hdsx-fw01-1).

D.1 Before the baseline

D.2 Open a round

On the console, signed in as dm01 / Hdsx-dm01-1:

1. Population › Rounds, New round. The page says "The round number is assigned automatically; set the fieldwork dates". On a server with no round the number is 0.
2. Start date and End date: the first and last day of fieldwork, in the site's calendar (Ethiopian at Arba Minch). The button beside each box opens a calendar.
3. Description, for example Baseline enumeration or Round 1 follow-up.
4. Save.

You see "Round 0 created" and the round with Current. On the list each round is Ended, Current or Upcoming, from today's date. The console and the tablets work in the highest-numbered round that has started.

No day belongs to two rounds. A new round starts after the previous round's end date. A date inside another round is refused: "The start date … falls inside round …". A gap between rounds is allowed.

To end a round early, open it, Edit, set the End date to the last day of fieldwork, Save ("Round 0 updated"). Then create the next round from the following day.

A round has no Close button: it ends on its end date.

The tablet files follow by themselves about a minute after Save: Tablets › Tablet export says "The register was changed on the console. The Households and DSS events exports start by themselves at about …". Execute all on that page writes them at once.

Example: round 0 from 2019-02-10 EC to 2019-02-19 EC; round 1 from 2019-02-20 EC to 2019-07-22 EC.

D.3 Bring the round to the tablets

On each tablet, signed in as the supervisor sv01 / Hdsx-sv01-1:

1. Sync on Home.
2. Sync downloads, Synchronize all.

Every part shows "last sync …". The tablet now holds the new round. If the tablet holds forms not yet accepted, the download stops with Upload your data first: the field worker uploads first (chapter E).

D.4 The baseline on the tablet (round 0)

The field worker signs in (fw01 / Hdsx-fw01-1), chooses the working area down to the subvillage (Muja) and taps Household on Home. The list has three tabs, Not visited, Visit not possible and Visited: the work left in the round.

At each house:

1. New household, then Add new Household (the field worker is at the house). Pre-register Household is for a household that will be visited later.
2. The tablet opens the forms in order: Location Registration (the house, with Get GPS Location), the household, then the visit.
3. On the visit screen, add each person who lives there with Member Enumeration, and the modules offered for them.
4. Finish visit.

The tablet gives every ID itself, for example the house MUJ000001, the household MUJ00000100 and the first person MUJ000001001. When nobody can answer, the field worker records Visit not possible; the household moves to that tab.

D.5 An update round on the tablet (round 1 and later)

In a new round every household starts again on Not visited.

1. Tap the household, Create visit.
2. Select respondent: a resident aged 18 or over; Respondent from another household; or The visit is not possible (the visit form records why).
3. The visit form asks what happened since the last visit. These answers are a checklist; they do not open the events.
4. Record each change with its event: + on the household row for the household's events, + on a person's row for that person's.
5. Finish visit. The household moves to Visited.

Member enumeration after the baseline first asks whether the person was living there at the last visit and missed. No stops it: "Do not enumerate this person. If they moved in since the last visit, register them with External in-migration (from outside the HDSS) or Internal in-migration (from another household of the HDSS). If they were born since, register them with Birth registration."

D.6 During and at the end of a round

Every day the field workers upload (Sync, Sync uploads) and the data manager follows the daily loop of chapter E.

To follow progress, open Monitoring, tab Overview: the round's progress, the field workers and the households not visited.

Before opening the next round:

Then create the next round as in D.2, from the day after the current one ends.

E. Daily data

The data manager's daily loop: the tablets upload, the console validates the records and puts them into the register, the data manager reviews what was refused or flagged, the tablets learn the verdict, and Monitoring shows the forms that are still missing.

Release: HDS-Explorer 1.0.0 build 7, tablet app 1.0.0 build 4-local. On the console, sign in as the data manager dm01 / Hdsx-dm01-1. On the tablet, the field worker is fw01 / Hdsx-fw01-1 and the supervisor sv01 / Hdsx-sv01-1.

E.1 The tablets upload

On each tablet, signed in as fw01 / Hdsx-fw01-1:

1. Sync on Home, tab Sync uploads.
2. Select all.
3. Upload selected forms.

Upload details opens with the totals, for example "Core forms: 7 uploaded, 0 with errors". The core forms go first, then the questionnaires (SES, verbal autopsy and the modules). A questionnaire waits until its visit is on the server.

A refused form carries one of three labels:

E.2 What the server does with an upload

Settings › System, tab General, section Submissions, setting When data is uploaded:

A new server starts on Validate and execute it. With that choice there is no run to start: go straight to Review (E.4). To check records before they reach the register, choose Validate it, Save, and run Validate & execute every day (E.3).

E.3 Validate & execute

Submissions › Validate & execute. The page shows the records staged now, per event: Staged, Held back (flagged or returned) and Refused in last run, with Would go in and Would be refused after a validation. Tab Runs lists the past runs.

Validate (see what would happen, nothing is written):

1. Validate. A dialog says what it does and how many records are staged.
2. Start. The run's steps and progress show; its page opens when it ends.
3. The run's page lists each record as Would go in, Would be refused or Held back, with why.

Validate & execute (the everyday run):

1. Validate & execute, then Start in the dialog.
2. Each record is validated as if the records before it had gone in. Those that pass go into the register; those that fail are refused with the reason. Flagged records not approved yet, and returned records, wait.
3. The run's page shows "N executed · N refused · N held".

The tablet files are written again by themselves after a run, so the supervisors' next download carries the new households.

Advanced holds rarer runs: a run with a limit for a large backlog, building or executing the queue in parts, and Retry refused records once the cause is fixed elsewhere.

E.4 Review

Submissions › Review is the data manager's work list. It has these tabs:

Core records and add-on questionnaires are listed together; the add-on rows sit under Add-on forms.

Open a record

On Would be refused, Flagged and Returned, Open on a row shows the record: its answers and its state, and As uploaded for the record exactly as the tablet sent it. The actions below are in the page's header. On the tab, the same actions apply to several ticked rows at once.

On Refused, the form name opens the staged record. Correct it there and Save & reprocess (it goes in with the next run), or Invalidate it. A refused add-on questionnaire opens with Repair: correct the answers, then Replay.

Return it with a note

For a record the field worker can correct:

1. Return with a note.
2. The dialog Return to the collector asks for the Note to the collector: what to correct.
3. Return with a note.

The record moves to Returned and is not executed until the corrected copy arrives. A record already executed, an edit, or one whose collector cannot receive it shows "Exclude only: the collector cannot receive it".

Exclude it with a reason

For a record that must never reach the register (a duplicate, a test, a visit that never took place):

1. Exclude.
2. The dialog Exclude the record asks Why it is excluded.
3. Exclude.

The record never goes into the register or its dataset, and the collector's tablet shows it as Excluded.

Undo an exclusion

Open the record, Undo exclusion, confirm. "The record is staged again and goes in with the next run, after review if it is flagged." The page keeps the exclusion with "Exclusion undone".

Approve a flagged record

On Flagged, tick the record, Approve. It goes in with the next run; Execute now puts it in at once. When records are executed at upload, the flags are for information only.

Dismiss

On Refused, Dismiss selected with a Reason takes a record that will never be sent again off the open list. It changes nothing else: sent again unchanged, it is refused again.

A supervisor opens Review for the records of their areas; the actions are the data manager's.

E.5 The tablet gets the verdict

When the field worker opens Sync uploads, the tablet asks the server what became of everything it sent.

A returned record can only be corrected on the tablet that collected it.

A supervisor's download stops with Upload your data first while the tablet holds forms not yet sent or refused. Upload, correct, then Synchronize all again.

E.6 Missing forms

Monitoring, tab Missing forms: "The forms a visit required of a resident and did not bring." Choose Days back, Filter. Three lists:

• Required per visit: the visit, household, member and form missing.
• Missing follow-ons: a record whose answers made a follow-on form due that never came.
• Deaths waiting for their verbal autopsy: once the waiting period has passed since the death.

The page writes nothing. Give the list to the supervisors; the field worker collects the forms at the next visit.

E.7 Common refusals

F. Forms

The questionnaires the tablets collect, how a newer standard arrives, how a site adds its own questions or forms, and how to download what was collected.

Release: HDS-Explorer 1.0.0 build 7. Release pack: release-pack-standard-2.zip.

F.1 The kinds of forms

Forms › Forms lists every form, with its Kind and Source:

Source is Standard (from a release pack) or Site (the site's own). Each form's page has the tabs Details, Build, Preview, Versions, Mappings and Follow-ons.

On a standard form a site changes only Modules and Enabled (Details, Edit details). Switch off only the add-ons the site does not collect.

F.2 Import a newer release pack

The standard forms arrive as a release pack. Download the newest from https://apps.techallyconsult.com/hds-explorer/server/release-pack-standard-2.zip.

Signed in as admin / Hdsx-admin-1:

1. Forms › Release packs, box Import a release pack.
2. Release pack (.zip): choose the file. Review.
3. The page Review pack … lists each form with its Outcome and What happens. It says "Nothing has been written."
4. Import (box Import this pack).

The result page, Pack … imported, says what happened to each form:

Import packs in order: a pack refused with "Import the earlier releases first" needs the earlier pack. Importing the same pack again says "Pack … changed nothing: this site already holds every form in it."

The tablets receive the new versions at their next Synchronize all. Records already collected keep their version.

F.3 Site questions and core extensions

A site adds questions to a standard form; it never changes the standard ones. Open the form, Build, Edit: the builder opens the site copy draft. Hover between two questions and choose + Add site question. Save the draft, then publish it from Versions (Review, Publish). The site's questions are carried onto each newer standard version a pack brings.

Forms › Core extensions is a second way to add questions to a core event: a separate questionnaire the tablet opens straight after the event is finished. Each row is one core event; its menu has Sample, Upload and Map columns, and it reaches the tablets only when Enabled. Prefer site questions.

F.4 Form Builder

The Form Builder is the Build and Preview tabs of a form's page.

A site form. Forms › Forms, New site form. Fill in Name, Form id (it starts with the site code, am_), who it is asked of, the age band, sex and at least one module. Create form. The form opens on Build with an empty draft.

Build shows a version page by page, as the tablet shows it. Edit opens it for changes:

• + Add question here and + Add repeat here between questions; + Add page in the outline.
• Click a question to open it in the drawer: its text, type, Required, and the rules (Show when, Locked when, Accept when).
• Save draft v1 keeps the edits as a draft.

Preview runs the version, or the unsaved edits, page by page as the tablet runs it. Rules run live; nothing is saved.

Publish. Versions, Review, Publish. A published version can never be changed. The tablets receive the form at their next Synchronize all. A changed form is a new version.

F.5 XLSForm

On Build, the Form file menu:

After Import XLSForm… the report XLSForm import says how many questions and option lists were converted, which names were Renamed, and the items To look at. Download report (CSV) and keep it with the form's files. Fix the items in Build, then publish.

On a standard form, Import XLSForm is refused: a site adds site questions there, not a whole form.

F.6 Download collected answers

Signed in as dm01 / Hdsx-dm01-1:

1. Data › Form datasets: "Everything collected with a form. Pick one to browse its records and download its dataset."
2. Choose the form. Filter by date, Round, area, Form version or codes if needed.
3. Download: Dataset (CSV), Labelled (CSV), Stata, SPSS, Codebook or Codebook (PDF).

One row per record, all versions together. Each repeat group is a dataset of its own, under Repeat groups. A plain download leaves out the columns that identify a person; a data manager also has the Identified downloads. Every download is logged under Data › Export log.

G. The data

Where HDS-Explorer keeps its data, how to read it with an account that cannot change anything, and which table holds what you see on the console and the tablet.

Everything is in one MySQL database, hds_explorer_db, on port 3307 of the server. MySQL listens only on the server itself, so the commands below run on the server.

Never change data in the database directly. The register, the uploads and the tablet files are kept in step by the server; a row changed by hand breaks that without a message. Read in SQL; change on the console or with a correction form on the tablet.

G.1 Create the read-only account

Once, as MySQL's root.

Windows, in PowerShell as Administrator. It asks for a password: use mysql_admin_password from C:\hdsx\credentials.txt.

& C:\hdsx\mysql-8.4\bin\mysql.exe -h 127.0.0.1 -P 3307 -u root -p

Ubuntu (root password Hdsx-root-1):

mysql -h 127.0.0.1 -P 3307 -u root -pHdsx-root-1

Then:

CREATE USER 'hdsx_read'@'localhost' IDENTIFIED BY 'Hdsx-read-1';
GRANT SELECT, SHOW VIEW ON hds_explorer_db.* TO 'hdsx_read'@'localhost';
exit

G.2 Run a query

Windows:

& C:\hdsx\mysql-8.4\bin\mysql.exe -h 127.0.0.1 -P 3307 -u hdsx_read -pHdsx-read-1 hds_explorer_db

Ubuntu:

mysql -h 127.0.0.1 -P 3307 -u hdsx_read -pHdsx-read-1 hds_explorer_db

At the mysql> prompt, type a query ending with ;. For example, the subvillages:

SELECT code, name FROM region WHERE level = 'hierarchy5';

exit leaves. A change is refused: UPDATE command denied to user 'hdsx_read'@'localhost'.

Three things to know:

• Dates are Gregorian in every table, whatever calendar the console shows.
• Coded answers are stored as codes (M, ENU, HOH), not as the label the console shows.
• member has a row UNK, "Unknown Individual", standing in for an unknown father or mother. The console leaves it out of its counts.

G.3 Table map

Every event row carries the visit_code of the visit it was collected in.

Do not read _user.password: it is a hash.

Tested with HDS-Explorer 1.0.0 build 7 on MySQL 8.4.

H. Moving from OpenHDS

For a site that already runs OpenHDS: copy its register (regions, locations, households, members and their history) into a new HDS-Explorer server. Nothing is written to OpenHDS.

Do it once, on a new server, after B.1 to B.3 and before the first tablet. It replaces B.4 to B.6: the region levels, the regions and the accounts come from OpenHDS. Then write the tablet files as in B.7.

You need:

• The admin / Hdsx-admin-1 account. Only an administrator sees these pages.
• The OpenHDS database's host, port, database name, and a MySQL user that can read it. The server must reach that MySQL over the network.
• A backup of the HDS-Explorer database, made just before H.12.

The numbers below come from a test run with an OpenHDS source of 10,000 households. Yours will differ.

H.1 Check the site readiness

Data › Maintenance › Import OpenHDS Data. The first step is Site readiness.

On a new site two checks fail, Region levels and Regions: "The site is not ready." The migration does not start until H.3 is done. The code check passes here, but that does not mean the OpenHDS codes fit: H.2 shows that.

H.2 Read the OpenHDS source

Data › Maintenance › Site setup from OpenHDS, box 1.

1. Type the host, port, database and MySQL user of the OpenHDS database.
2. Type the password. It is used for this request only and is not saved.
3. Read the source.

The read checks every location, household and member code, so it can take some minutes on a large source. The page then lists what it will create; in the test run: 2 levels, 21 regions and 5 users.

H.3 Region levels and regions

Box 2. Compare From source with Site value (the test source has Zone and Kebele).

1. Apply region levels.
2. The confirmation names the levels and the regions it creates. Confirm.

The page says "2 region levels are set and 21 regions are created". Regions that are deleted or voided in OpenHDS, or have no parent, are not created (the test source had 22, so 1 was left out).

H.4 Accounts

Box 3 lists the OpenHDS users that are not in HDS-Explorer yet.

1. Check the role of each one. Field workers get ROLE_FIELD_WORKER.
2. Keep or change the Default password. Every new user must change it at the first sign-in.
3. Create 5 users (the number is the users listed). Confirm.

The server does not keep the default password: give it to the users yourself.

H.5 ID rules

Box 4 checks every OpenHDS code against this server's ID rules. With the Standard rules every household is rejected (all 10,000 in the test run): OpenHDS codes a household with the code of its location.

1. In box 4, Open parameters, or go to Settings › ID rules.
2. Choose the preset that builds codes the way your OpenHDS does. The test source uses an area code plus 6 digits, with the household coded as its location: Simple. The page shows what changes.
3. Apply. The page says "The ID rules were saved", and Household shows "Same as its location".

A preset is refused for a kind of ID that already has records, so do this before the migration.

H.6 Check again

1. On Site setup from OpenHDS, box 1, type the password again and Read the source.
2. Box 4 must say No problems: the rejected count is 0. If not, go back to H.5.
3. Open Import OpenHDS Data. Site readiness says "The site is ready" and every check is Ready. Continue.

H.7 Connect

Step 1 of 7 (the bar at the top shows the step).

1. Type the host, port, database, user and password of the OpenHDS database.
2. Test connection. The page shows the MySQL version and the number of tables, for example "Connected to MySQL 8.4.10: 21 tables". The test clears the password: type it again.
3. Connect and map.

The server keeps the password in memory for this run only. After a server restart, type it again.

H.8 Map

The server matches the OpenHDS tables and columns with the register. On a standard OpenHDS database everything required is matched.

1. The message at the top must say "All required core tables and columns are mapped". If a table or column is not matched, choose its source. Each change is saved.
2. Next: preview.

Export mapping keeps the mapping for another site with the same OpenHDS database layout.

H.9 Preview

The rows to write for each kind of record (in the test run, 199,896 OpenHDS rows became 196,238 register rows). Check the counts against what you expect from OpenHDS. Next.

H.10 Value mappings

The page starts the validation when it opens and shows its progress every 3 seconds. Wait for it to finish.

1. For each field, check the HDS-Explorer code given to each OpenHDS value.
2. A value with no code: choose one, or add a custom code for the migration.
3. Save, then Validate again.

In the test run one value had no code: location type HOUSEHOLD has no residence code. Left at Keep as in source, the household residence is written empty and the run goes on. Choose a code (for example 1 · Rural, agrarian) if the site wants it filled.

H.11 Validate

The issues are grouped by rule. A Warning needs a decision; a Note is for information. The test run had 351 warnings and 2,108 notes, under 4 rules that need a decision, for example "Ends before it starts" (154) and "Member joins a household with no head" (122).

1. Open each rule under Need a decision to see its records.
2. For each record: accept it, exclude it, or fix it in OpenHDS and validate again.
3. When the page says "The run is ready to execute", go to Execute.

Rows the register refuses are skipped and listed in the summary.

H.12 Execute

Execute writes straight into the register. Back up the HDS-Explorer database first.

1. Read Before you start: the source, the region levels and the issue counts.
2. Tick "I understand that the migration writes directly to the register".
3. Start the migration. Confirm.
4. Keep the page open. It shows the progress of each kind of record.

H.13 Read the summary

The summary opens when the run ends. The status is Executed (test run: 196,238 rows written, 0 not written).

1. Check the written count of each kind of record against the OpenHDS rows.
2. Open Reconciliation: occupied and vacant households, members out-migrated and dead (test run: 9,976 occupied, 24 vacant, 1,605 out-migrated, 337 dead).
3. Download all issues (CSV) to keep the issue list.

The dashboard now shows the residents and households (test run: 38,065 residents in 10,000 households).

Rollback, on the summary, deletes every record this run wrote.

H.14 After the migration

1. Write the tablet files: Tablets › Tablet export, as in B.7. Until then tablets cannot download the migrated records.
2. Give the default password to the new users (H.4).
3. If OpenHDS goes on collecting data for a while, run the migration again later: it reads only the rows that are new or changed.