DS Soteria — User Manual

DS Soteria is Digital Surveying's safety & inspection app: vehicle inspections, pre-job assessments, daily health & safety declarations and traffic-light equipment checks — designed to work fully offline in the field and sync when you're back in signal. This manual covers everything from filling in your first form to designing new ones. Sections 1–4 are for everyone; sections 5–8 are for designers and admins.

1 · Getting started

1.1 Signing in

Open soteria.digitalsurveying.co.za and press Sign in with Microsoft. Use your normal work (Microsoft 365) account — there is no separate Soteria password. Once signed in you stay signed in for 7 days, even offline, so field crews don't get locked out mid-shift.

1.2 Roles — what you can see

Roles come from your Microsoft 365 group membership automatically; an admin can override a person's role on the Users screen.

1.3 Install Soteria as an app (recommended for field work)

Soteria is an installable app (PWA). Installing it gives you a home-screen icon, full-screen use, offline support and push reminders.

• Android (Chrome): menu ⋮ → Add to Home screen → Install.
• iPhone / iPad (Safari): Share ⎋ → Add to Home Screen. (On iOS, reminders only work from the installed app.)
• Windows / Mac (Chrome or Edge): click the install icon in the address bar.

1.4 Turn on reminders

On the Dashboard press 🔔 Enable reminders and allow notifications. You'll then get a push notification when a scheduled form (e.g. a daily declaration) is due and not yet done. This is per device — enable it on the phone you actually carry.

1.5 The screens

2 · Everyday use — filling forms

2.1 Opening a form

Go to 📋 Forms and tap the form card. Forms that are due for you today have a gold border and a DUE badge, and also appear in the Dashboard's 📌 Due card with a Fill now button.

2.2 Moving through a form

• Longer forms are split into pages — use the Next / Back buttons. You can't advance past a page with missing required answers; anything missing is highlighted.
• Required questions are marked with a red *.
• Some questions only appear when relevant — e.g. "Reason vehicle is not safe" only shows once you answer "No" to "Vehicle safe to operate?". Don't look for hidden questions; they appear on their own.
• Your progress is saved automatically as a draft on the device. If you close the app or the battery dies, reopen the form and continue where you left off. ↺ Reset clears the draft and starts over.
• If the form is scored you'll see a live 🎯 score chip update as you answer.

2.3 Traffic lights

The heart of most checklists. Tap the disc that matches what you found:

• Green — in order, no issues.
• Amber — usable, but something needs attention.
• Red — not in order / unsafe.

When you flag amber or red, a strip opens below the question asking for a note (usually required — describe what you found) and optionally photos of the problem. Be specific in notes: they go into reports, printed PDFs and follow-up tasks word-for-word.

2.4 Yes / No questions

Answer with the Yes / No pills. On safety questions one of the answers is the "problem" answer (e.g. "Do you have any injuries?" — Yes is the problem) — it shows red or amber and opens the same note/photo strip as a traffic light. The good answer shows green. Questions where neither answer is a problem are simply informational.

2.5 Photos, files & signatures

• 📷 Photo — take a photo with the camera or pick from the gallery. Photos are automatically shrunk on the device before upload, so they won't eat your data.
• 📎 File upload — attach any document.
• ✍️ Signature — sign with your finger in the box; Clear restarts the signature.

2.6 Barcodes, GPS and pickers

• 🏷️ Barcode / QR — press scan and point the camera at the code; you can also type the code manually.
• 📍 GPS location — press the button to capture where you are. Allow location access when asked.
• 👤 Person picker — choose a colleague from the staff list.
• 🚙 Asset picker — choose a vehicle, equipment item, site or project from the company list. The vehicle list comes live from the DS Koios fleet register, so it's always current.

2.7 Repeating items and checklist grids

• A repeating group (e.g. "Defects found") starts empty — press the add button for each item and fill in its small set of fields. The 🗑 icon removes an item.
• A checklist grid is a table: one row per item to check (Tyres, Lights, Mirrors…), one column per thing to record (usually a traffic light per row).

2.8 Submitting

Press Submit on the last page. If you're online it uploads immediately; if not, it queues — see the next section. After submitting, the form is final: submissions can't be edited, which is what makes them trustworthy records. If you made a mistake, submit again and tell your supervisor which one counts.

3 · Working offline

Soteria is built to be used underground, on remote sites and in airplane mode. Everything about filling a form works with no signal at all.

3.1 How it works

• Every form you can fill is stored on your device and refreshed automatically whenever you're online. Open the app once while online and you're set for the field.
• Submitting offline puts the submission (photos included) into the outbox on your device. A badge in the top bar shows how many are queued.
• The outbox sends itself automatically: when the app opens, when signal returns, and it retries every minute while anything is pending. You never need to re-enter anything.
• The times recorded are when you actually filled the form in — a 06:40 underground declaration shows as 06:40 even if it only syncs at lunch.

3.2 If a queued submission won't send

Nothing queued is ever silently thrown away. If the server rejects a submission (for example the form was changed while you were offline and something required is missing), it stays in the queue and the app shows what's wrong. Ask a designer to check the form if this happens.

4 · Your submissions

4.1 The register

🗂️ Submissions lists your completed forms (managers see everyone's). Each row shows the overall traffic light (the worst light anywhere in the submission), score, version filled against, photo count and review status. Filter by form, person, light, status and date range.

4.2 Opening & printing

Tap a row to open the full submission exactly as filled — photos and signatures included. 🖨 Print / view PDF opens a professionally branded PDF you can save or print; ⬇ Download PDF saves it directly.

4.3 Review status

Submissions start as awaiting review; a manager checks them and marks them ✔ reviewed (optionally with a note). The status is visible on the register, in the detail view and stamped on the PDF.

5 · Designing forms (designers & admins)

5.1 The golden rule: drafts vs published versions

Every form has two lives:

• The draft — your working copy. Edit it freely; nobody filling forms sees draft changes.
• Published versions — frozen snapshots. Pressing 🚀 Publish freezes the current draft as version 1, 2, 3… and that's what people fill in.

Every submission remembers exactly which version it was filled against, forever. Old submissions always display, print and export with the questions as they were on the day — so you can improve a form without corrupting history. Publish is not undoable (versions are permanent), but you can always keep editing and publish again.

5.2 Creating a form

1. Go to 📋 Forms → ＋ New form and give it a name.
2. In the designer, open ⚙ Details to set the icon (any emoji), category, description, and — for safety forms — the red-finding escalation (see 5.8).
3. Add fields, save, 👁 Preview to test it exactly as a filler will see it, then 🚀 Publish.

You can also ⧉ duplicate an existing form as a starting point.

5.3 The designer screen

Three panels, left to right:

• Palette — every field type, grouped (Text, Numbers, Choices, Date & time, Capture, People & assets, Structure). Click to add; the new field lands under the currently selected one.
• Canvas — the form as a list of fields. Click a field to select it; ▲▼ reorder, ⧉ duplicates, ✕ removes. Tabs across the top switch between pages (＋ adds a page, 🗑 deletes the current one).
• Properties — the settings of the selected field (nothing selected = page title).

An unsaved badge appears whenever you have unsaved changes — press 💾 Save often.

5.4 Properties every field has

5.5 Conditional questions ("Show only when…")

Any input field can be hidden until another answer makes it relevant. In the properties panel choose the controlling question, then equals / does not equal, and the value to compare — for a Yes/No question type yes or no; for a traffic light green/amber/red; for choices, the exact option text.

Classic pattern: "Vehicle safe to operate?" (Yes/No, "No" is the problem) followed by "Reason vehicle is not safe" shown only when the answer equals no, required. Hidden questions never block submission and are excluded from scoring.

5.6 Traffic lights & escalation strips

On each traffic-light field you configure what happens when it's flagged:

Make notes required on anything a supervisor will act on — a bare amber with no explanation is worthless a week later.

5.7 Yes/No polarity — "which answer is the problem?"

A plain Yes/No is informational. Setting Which answer is a problem? turns it into a check:

• "Yes" is the problem — e.g. Do you have any injuries?
• "No" is the problem — e.g. Is your PPE complete?

The problem answer renders red (or amber, per Flag severity), opens the same note/photo strip as a traffic light, counts toward the submission's overall light, appears on flag dashboards — and if severity is red, triggers Hercules escalation like any red traffic light. Don't build a separate "traffic light phrased as a question" — polarity does it properly.

5.8 Red-finding escalation to DS Hercules

In ⚙ Details, per form: if any answer in a submission comes out 🔴 red, Soteria creates one high-priority task in DS Hercules (due in 2 days) listing every red item with its notes and a link back to the submission. Choose who gets it:

• (no escalation) — off.
• A specific person — e.g. the workshop manager for vehicle inspections.
• Whoever submits the form — "fix what you found" forms.

Optionally add a 👁 watcher — they follow the task in Hercules (Tasks → Following) and can monitor completion without owning it.

5.9 Scoring & pass thresholds

Press 🎯 Scoring in the designer toolbar to score submissions of the form:

• Traffic lights score green 100% · amber 50% · red 0 of their weight.
• Yes/No questions with a problem answer score good 100% · bad 0.
• Ratings score proportionally (3 of 5 stars = 60%).
• Each scorable field gets a weight in its properties (default 1; 0 = not scored; heavier = matters more).
• Unanswered optional questions and hidden questions don't count against the score.
• Set the pass threshold % — submissions show PASS/FAIL on the register, detail view, PDFs and exports, and the filler sees a live 🎯 chip while filling.

Scoring rules are frozen into each published version — changing them affects the next publish onward.

5.10 Repeating groups & checklist grids

• 🔁 Repeating group — for "zero or more of something": defects found, passengers, tools issued. Define the small set of fields per item (any normal type; mark per-item required as needed) and the label of the add button ("Add defect"). The filler adds as many items as apply.
• ▦ Checklist grid — for "the same check across a fixed list": row labels one per line (Tyres & wheels, Lights, Mirrors…), plus columns (traffic light, text, number, select or yes/no per row). Prefer a grid over ten copy-pasted traffic lights — it's faster to fill and reports cleaner.

Structure can't nest — no repeaters inside repeaters or grids.

5.11 Asset pickers & lookup lists

The 🚙 Asset picker field takes its choices from a named list. Lists are managed in Settings → Asset picker lists — except linked ones: the vehicle list is fed live from the DS Koios fleet register (a 🔗 banner marks it) and cannot be edited here; add or retire vehicles in Koios. Create your own lists (equipment, site…) and reference them from the field's Picker list property.

5.12 Prefill for external client forms

On text, email and phone fields you can set ✉️ Prefill from invite (client name / email / company / phone). This only matters for forms sent to external clients (see 7.6): the field arrives pre-filled from the invite, still editable. It does nothing for normal in-app fills.

5.13 Testing and publishing

1. 👁 Preview runs the real fill experience against your draft — test the conditional logic and required rules, on a phone-sized window too.
2. 💾 Save, then 🚀 Publish. The version number increments and field devices pick it up automatically when next online.

6 · Field type reference

Everything on the designer palette. "Extra settings" is what appears in the properties panel beyond the standard label / required / help / show-when.

Text

Numbers

Choices

Date & time

Capture

People & assets

Structure (not questions)

7 · Managers & admins

7.1 Reviewing submissions

New submissions arrive as ⏳ awaiting review. The Dashboard's "Awaiting review" tile jumps to the filtered register; tick ✔ on a row for a quick sign-off, or open the submission and review with a note. A review can be undone from the detail view. Reviewed status and reviewer are stamped onto the PDF.

7.2 Exports

• ⬇ CSV — the register as a spreadsheet-friendly file, honouring your current filters. Filtered to one form it also adds a column per question.
• ⬇ XLSX — the detailed per-form report: pick a form filter first. One row per submission with the full detail block (who, when, status, light, score, review) plus one column for every question of the form in form order — grid rows individually labelled, traffic answers colour-coded, notes included. This is the one to hand to auditors.

7.3 Scheduled forms & reminders

Settings → 📌 Scheduled forms: schedule a form daily, weekdays, weekly (pick the day) or monthly (pick the date), with a due time, assigned to everyone, a role, or specific people. From the due time onward, anyone who hasn't submitted that form in the current period gets a push reminder (one nag per person per period — no spam) plus a DUE badge and Dashboard entry. ▶ Run reminders triggers a manual pass (admins).

7.4 PDF layouts

Settings → 🖨 PDF layouts: design the page chrome of printed submissions — logo, banner, headers, footers — in a WYSIWYG A4 designer (drag text / image / rectangle / line elements). Elements can repeat on every page and anchor to the top or bottom border; the questions & answers flow between them. Text supports tokens like {{form_name}}, {{submitted_by}}, {{submitted_at}}, {{overall_light}}, {{score_pct}}, {{page}}/{{pages}}. A layout can be tied to one form or set as the global default; without any, the built-in DS design is used. Preview renders against the latest real submission.

7.5 Asset picker lists

Settings → Asset picker lists: add/edit the values behind asset picker fields. Lists marked 🔗 are linked to a sister system (vehicles ← DS Koios fleet) — manage those in the source system; ↻ Refresh forces a re-fetch.

7.6 External client forms

Forms in a category named External-Eos can be emailed to clients from DS Eos (Activity → 📨 Client Forms). The client gets a branded email with a secure personal link and completes the form in the browser — no account, no app. Their submission lands in the normal register (submitted by "External client", the actual client identity on record) and goes through review like any other. Designer notes:

• Keep external forms to simple field types (text, choices, ratings, dates…). Soteria refuses to send a form whose required fields include types a client can't complete in the public page, and tells the sender which fields are the problem.
• Use prefill roles (5.12) so the client's name/email/company arrive pre-filled.
• Invites expire and are single-use per submission; Eos shows sent / opened / completed per activity.

7.7 Users & roles

👥 Users (admin): everyone who has signed in, with role and activity. Roles resolve automatically from Microsoft 365 groups at each sign-in; overrides you set here stick. Deactivate anyone who shouldn't have access — deactivation applies within a minute, even if they're already signed in.

7.8 Where the data lives

Submissions are permanent records: they can't be edited after submission, deletions are soft (recoverable by an admin), photos/signatures are stored server-side and stream only to signed-in users, and every submission remembers its exact form version. PDFs and exports can be regenerated at any time — you never need to hoard downloaded copies.

8 · Troubleshooting & FAQ

Dates throughout DS systems are shown as dd/mm/yyyy. For anything this manual doesn't answer, contact your system administrator.