16 — Creating a surveyor (mobile user)

A surveyor is just a Frappe User — there is no separate “Surveyor” doctype. What makes a User able to use the mobile app is the right pair of roles. Get the roles wrong and the symptom is confusing (login is rejected, or the app loads but shows nothing), so follow this exactly.

TL;DR

Create a User → set a password → give them both roles below → done.

Role	Why it’s needed	What breaks without it
Mobile User	The mobile-control app gates all mobile logins on this role.	Login is rejected with “User is not allowed to use mobile app” — even with a correct password.
Swasti Surveyor	Grants read/create permission on the forms (Member, Scheme/Document Application + follow-ups, Health Screening, masters).	Login may succeed but the app has no data and can’t save.

The app authenticates with username + password (a normal Frappe session login through mobile_auth). There are no API keys to generate.

Step-by-step (Frappe Desk)

Do this as Administrator or a System Manager on the target site (e.g. stg.swasti.mform.in).

New User. Go to User list → New.
Identity. Enter the surveyor’s Email (this becomes their login username), First Name, and (optional) mobile number.
User type = System User. Leave it as the default System User — not Website User. Mobile login needs a System User.
Enabled. Make sure Enabled is ticked. A disabled user can’t log in.
Save.
Set a password. Either:
- tick Send welcome email (if SMTP is configured) so they set their own, or
- after saving, use … menu → Set Password (or Reset Password) to set one yourself and share it securely.
Add roles. In the Roles section, add both:
- Mobile User
- Swasti Surveyor
Save. The user can now log into the app with their email + password.

That’s the whole requirement today. The first time they log in and sync, the app pulls all the masters (members in their scope, schemes, documents, geography) to the device.

Geography / program scope (current state)

Right now surveyors are not geography-restricted at the permission layer — the staging test surveyor has no User Permission records and can see all data the roles allow. Member records carry a surveyor link (→ User) and full geography links (State / District / Block / Gram Panchayat / Village), so scoping can be layered on later via User Permission records (e.g. restrict a surveyor to a District), but that isn’t wired or required yet.

When we do add geography scoping, do not lift the rel-mis program-assignment/geography model wholesale — it’s a reference, not a template for Swasti. Design it against Swasti’s own donor/partner/geography shape.

Troubleshooting

Symptom	Cause	Fix
”User is not allowed to use mobile app” on login	Missing the Mobile User role	Add `Mobile User` to the user’s Roles.
Login works, but no members / empty lists	Missing Swasti Surveyor role, or first sync hasn’t run	Add the role; then pull-to-refresh on the Home screen.
Login fails with correct password	User Disabled, or wrong site/URL in the app flavour	Re-enable the user; confirm the build points at the right environment.
Dropdowns show “No options available”	Not a user problem — the doctype isn’t in the Mobile Configuration manifest	See the new-doctype section of note 15.

Why it’s only two roles (under the hood)

The server-side mobile_control app checks every mobile login against a single allow-list:

MOBILE_USER_ROLES = ["Mobile User"]
# validate_mobile_user_role(): if the user has none of these roles →
#   raise PermissionError("User is not allowed to use mobile app")

So Mobile User is the gate to get in, and Swasti Surveyor is what gives you something to do once you’re in. Everything else (which forms, which fields) flows from the Swasti Surveyor role’s DocPerms and the Mobile Configuration manifest.