Admin Guide

For the person who sets up the devices and looks after them. Device roles, your Supabase project, sites and clinicians, the encounter form, backups, and replacing a device.

This page picks up after the first device is installed and set up. For that, see the Setup Guide. For what the clinicians using these devices see every day, see the User Guide.

Admin and standard devices

Every device is either Admin or Standard. The role is chosen once, during first-run setup, on the step headed Name this device, under the question What is this device allowed to do?. There are exactly two answers:

• Enter and view records (most devices) makes the device Standard.
• Also change the form and clinic settings for everyone makes it Admin.

That question is the whole permission model. There is no admin password.

What an admin device can do that a standard one cannot:

• It shows the Form setup tab. On a standard device that tab does not appear at all.
• It sends the form layout and the clinic presets to the rest of the team when it syncs. A standard device only receives them.

Everything else is the same on both. Every device sees the Admin tab and all six of its cards, so any clinician can rename their device, take a backup, restore one, check the sync status, and see how many records are waiting to upload. That is deliberate: a clinician who cannot take a backup without you is a clinician who loses a day of work when you are not there.

To see the role of the device in your hand, open the Admin tab. The first card, This device, shows Name, Role (Admin or Standard), Device ID, and Mode (Offline only or Cloud sync).

Changing a device's role later

The role cannot be changed inside the app. On a cloud team it lives in the devices table of your Supabase project, and the app reads it from there on every sync.

Two rules matter when you are setting a team up:

• Only the first device to register in a project can make itself an admin. That is the device you set the project up with.
• Every device after that registers as Standard, even if the person chose Also change the form and clinic settings for everyone. The Form setup tab may show for the rest of that session, and is gone the next time the app is opened. Nothing is wrong; the project corrected the role. Do not use that tab in the meantime.

To make a second device an admin:

1. On that device, open Admin and note the Device ID. It shows the first 8 characters.
2. In Supabase, open the Table Editor and open the devices table.
3. Find the row whose id starts with those characters, and check the name matches the device.
4. Change role from standard to admin and save.
5. On the device, open Admin and tap Sync now, then close the app fully and open it again. The Form setup tab appears. It does not appear until the app has been reopened.

To take admin away, set role back to standard the same way. Do that before you hand a device on to someone else.

An offline only device keeps the role it was given at setup. There is no project to read a new role from, so the only way to change it is to set the device up again from the start.

A lost or stolen device

Your Supabase project can stop accepting anything from a device you no longer control. In the devices table, set that device's revoked_at to the current date and time. From then on the project refuses its records, and the device cannot clear its own revocation.

Connecting to your Supabase project

Cloud sync means every device on the team ends up with the same records, and there is a copy off the device. The project is created and owned by your organization. Creating it and running the setup SQL is covered in the Setup Guide, under If your team syncs to a cloud.

You need two things from Supabase, under Settings then API Keys: the Project URL and the Publishable key (on older projects, the legacy anon key).

During first-run setup

1. On the first screen, Set up this device, choose Connect to our clinic cloud.
2. On Connect to your cloud, paste the Project URL and the Project key.
3. Tap Check and continue. The app contacts the project and checks the tables before it accepts the key.

On a device that is already offline only

Open Admin, find the Cloud sync card, and tap Connect this device to a cloud. It asks for the URL, then the key, checks the tables, and registers the device in the project. Records already on the device upload on the next sync.

What the errors mean

• That does not look like a Supabase project URL. During first-run setup that is the exact wording. From the Admin tab the same problem reads That URL or key does not look right. Either way, the URL must be the plain project address, like https://yourproject.supabase.co, with nothing after it.
• Could not reach the project tables. The device has no connection, or the key is wrong.
• Connected, but the records table was not found. The project exists but is empty. During first-run setup the message ends Run the setup SQL on this Supabase project first.; from the Admin tab it ends Run the setup SQL on that project first. Both mean the same thing. Run supabase/setup.sql in the SQL editor, then try again.

Adding more devices

There is no invite code and no join step. Every device runs the same four-step setup, and the ones that use the same Project URL and Project key are on the same team.

1. Install the app on the new device and open it.
2. Choose Connect to our clinic cloud and paste your project URL and key.
3. On Name this device, give it a name you will recognise on a list, like iPad 2 - triage or Grace's tablet. That name appears on the records this device files, so a vague name is a problem later.
4. Leave the role as Enter and view records (most devices).
5. On Where is this device working?, type the sites and clinicians unless an admin device has already sent its lists to the project. If those lists exist, they arrive on the first sync and replace whatever is typed here, so you can leave both boxes empty. If no device has ever set them, an empty box leaves this device filing every visit under the placeholder Site A, and the records are useless in a report. When in doubt, type them.

The device pulls down the form, the presets and the record history on its first sync. On a slow connection, leave it open until the top-right button reads Synced.

How sync works

Sync is automatic. Nobody has to remember it. On a device connected to a cloud, the app syncs shortly after it starts, whenever the device comes back online, whenever the app is brought back to the front, and every two minutes while it is open.

The button at the top right is the honest status of this device:

• Offline only means there is no cloud on this device. Records stay here. The button does nothing.
• Connected means the project is reachable but nothing has synced yet this session. This is what a device shows just after the app is opened.
• Offline means records are saved on this device and will go up when there is signal.
• Pending, with a chip like 7 pending, means that many records are still waiting to upload.
• Syncing means it is sending and receiving now.
• Synced means every record on this device is in your project.
• Sync error means something failed. Tap it to retry, and check the connection and the key.

Tapping the button forces a sync now. So does Sync now on the Cloud sync card in Admin, which also reports the result in words: Sync finished. 12 records uploaded. Nothing is waiting., or Sync finished. Everything was already up to date.

The Cloud sync card also shows Waiting to sync and Live updates. Live updates mean a record saved on another device appears here without anyone pressing Sync. If Live updates stays on Connected, waiting for the first update, re-run the setup SQL on the project. It adds the tables to the realtime publication. Sync still works either way.

Sites and clinicians

These two lists fill the Site and Provider pickers on the encounter form. Site is required on every visit, so the list has to be right before a clinic starts.

In the Admin tab, the Sites and clinicians card shows the current lists and has two buttons, Edit sites and Edit clinicians. Each opens a box where you type one entry per line.

• Commas are safe inside a line. Grace N., clinical officer is one clinician, not two.
• An empty list is refused: You need at least one site. An empty list would block every save.
• After saving you see how many were saved, and a reminder to reopen the encounter form to see them.

If a red bar reads This device is still filing records under placeholder names, the device is stamping every visit with Site A. Those records are useless in a report. Fix the lists before the next clinic.

Setting up the encounter form

On an admin device there is a Form setup tab. Its heading is Set up the encounter form. That is the form a clinician fills in after tapping + New visit; the app calls it the encounter form here and nowhere else. What you do here changes the form for everyone in your organization, so it is worth doing once, carefully, before a trip.

You can:

• Reorder sections by dragging the ⠿ handle. Put the sections your team uses most at the top.
• Rename a section by typing over its title. The new name is saved when you tap away.
• Hide a section you do not use with Hide, and bring it back with Show. Encounter and Patient are marked Always shown and cannot be hidden.
• Add your own section with + Add a section, then rename it.
• Add questions to a section you created. Tap Questions, type the question, pick a type, and tap Add. Built-in sections are marked Built in and take no extra questions.
• Edit a question in place: rename it, change its type, drag it to a new position, tick Required so a visit cannot be saved without it, or Remove it.
• Set the answers for a choice question with Choices, one per line, or the ends of a scale with Scale.

Question types are Short text, Long text, Single choice, Multiple choice, Number, Scale (0-N), Yes / No and Date. This is where you add anything the built-in form does not have, for example heart rate, respiratory rate or SpO2 in a section you call Extra vitals.

Changes save as you make them. The indicator at the top right reads Saving… and then Saved with the time the device saved, written in that device's own clock format. They reach the other devices on the next sync.

Answers already saved are never lost

Hiding a section, removing a question or deleting a section you made only changes what appears on the form from now on. Answers already saved on existing records are kept, and the app says so before it goes ahead. Renaming a question or changing its type also keeps the answers attached to it.

When the tab will not let you edit

• Read only means this is a standard device. Use an admin device.
• Form settings have not reached this device yet means the device has not pulled the organization's form. Go to Admin, tap Sync now, then come back. Editing is locked until then, because saving now would replace your organization's form with a blank one.
• That change was not saved. means the form is unchanged. Check the device is online and try again.

Access to Care, Rx Presets and Provider are not in the list. They are kept so old records still read correctly, but they do not appear on the encounter form.

What you cannot change in the app

Only two lists are editable on a device: sites and clinicians. The rest of the clinical configuration arrives from your project and is not editable in the app today:

• the medication formulary that fills the drug picker
• the lab tests, their result types and their normal ranges
• the chief complaint pills
• the procedure pills
• the referral types

These live as rows in the config table of your Supabase project. If your team needs a different formulary or a different lab panel, email md@damicohealth.org and we will help you set the values, or set them for you.

Two related things to know, so nobody hunts for them mid-clinic:

• If your project has no procedures configured, the whole Procedures section is left off the encounter form.
• Diagnosis is a free-text box. There is no ICD-10 search or code picker. Codes already saved on older records are kept, shown in the patient chart as Coded, and still included in the CSV export, but new codes cannot be added.

Backups

A backup is a single file holding every record on the device plus the form and preset settings. It never contains your cloud key or the device identity. Take one at the end of every clinic day, whether or not you use cloud sync.

1. Open the Admin tab and find the Backup and restore card.
2. Tap Download backup.
3. Save the file, named dh-emr-backup-2026-08-11.json, somewhere off the device: the Files app plus a laptop, or AirDrop to a teammate.

Restoring from a backup

On the Backup and restore card, tap Restore from a backup and pick the file. Restoring merges: nothing already on the device is lost, and where the same visit exists in both, the more recently saved version is kept. A visit deleted since the backup was taken is not brought back.

The app asks twice. The first question confirms the merge. The second asks:

• Also restore the settings from this file? Choosing OK replaces this device's form layout, sites, clinicians and formulary with the ones in the file. On an admin device those settings then go out to the whole team on the next sync.
• Choose Cancel to restore records only. That is almost always what you want. Say yes to settings only when you are deliberately rolling the organization's form back.

When it finishes it tells you exactly what happened, for example Restored: 12 added, 3 updated, 40 already newer here. 55 records on this device. Check that number against what you expected.

Moving to a new device

The Admin tab has a short version of this on the card headed Moving to a new device. In full:

1. On the old device, tap Download backup and save the file somewhere you can reach it.
2. If the old device uses cloud sync, also tap Sync now and wait for Nothing pending.
3. On the new device, open the app and run setup. Choose Connect to our clinic cloud with the same project URL and key, or Use this device on its own if your team is offline only. Give it its own name.
4. On the new device, open Admin and tap Restore from a backup. Pick the file. Choose Cancel when it asks about settings.
5. Check the record count matches before wiping the old device.

Importing from another cloud project

Use this when your team is moving to a new Supabase project and you do not want to leave the old records behind.

1. In the old Supabase project, export the records table as JSON.
2. On a device connected to the new project, open Admin and find the card headed Moving from another cloud project.
3. Tap Import records from a file and pick the export.

The records are merged into the device the same way a restore is, then uploaded to your current project on the next sync. It accepts either an app backup file or a Supabase JSON row export, and reports how many were added, updated, skipped, and how many rows it could not read.

If the app cannot read its records

A red bar reading This device cannot read its records. Do not enter more patients here. means the device has lost its records database. This is rare, and it happens most often on an iPad that was left unused for a long time or is very short on storage.

Saving is blocked while that bar is showing, so nothing overwrites what may still be recoverable. The device also keeps a second, older copy of the records on itself, and the app has refused to load it because it is behind. The bar tells you how many records that older copy holds and how many the device last had.

In order:

1. If your team uses cloud sync, the records are already in your project. Set the device up again and let it pull them down, or use another device.
2. If you have a backup file, tap Go to Admin to restore a backup and restore it. This is the safest way back.
3. Only if there is no backup file anywhere, tap Use the older copy instead. It tells you how many records it holds and what date it stops at. Anything entered after that date is gone. Take a backup immediately afterwards, before entering anything else.

A different, quieter bar reading Back this device up today. means the device is down to a single copy of its records: the second copy it keeps on itself is out of date, or was never written. It is not about free space, and nothing is lost yet. Download a backup now and every day after, and archive older visits off that device.

A bar reading Close the other tabs. means the app is open in more than one tab or window on this device. Close the others. Records entered in one can overwrite the other.

Getting the data out

The Analytics tab has an Export CSV button. It produces dh-emr-export-2026-08-11.csv, one row per visit, which opens in any spreadsheet and is what you use to build a report or hand data to a statistician. The tab itself shows totals, charts and a data-quality panel.

The app does not produce a PDF report and does not print a single patient's chart.

Free and supported

DH Field EMR is free, with every feature included. It is not a certified EHR and it is not HIPAA-compliant. It is built for global health field work outside the United States.

• Found a bug, or need a formulary or lab panel changed? Email md@damicohealth.org.
• If it helps your work, a donation keeps it going. Never required.