Administrator guide
Administrators look after who can use the system and what they can do, the list of places, the dictionaries (choice lists and compensation rates), the background jobs, and the email and SMS settings. The Administrator role always has every permission, so you can also do everything in the Compensation Officer guide.
Default role: Administrator Key permissions: users.manage roles.manage locations.manage dictionaries.manage jobs.manage settings.manage
First-day checklist
On a new installation the server creates the default roles, the 23 Kaduna LGAs with their 255 wards, and one administrator account (staff ID KADGIS-0001) from the settings your IT operator chose.
- Change the administrator password straight away under My account, and put your own name on the account.
- Check delivery settings (Messages › Delivery settings) so invitations and SMS actually go out. See below.
- Add areas under the wards where projects run (Locations).
- Replace the sample rates for economic trees, crops and buildings with the approved KADGIS rate schedule (Dictionaries), and check the choice lists.
- Review the roles. The defaults suit most offices; adjust them before inviting people.
- Invite staff, at least one Compensation Officer and the field surveyors.
Locations
Needs locations.manage
Places are kept in three levels: LGA › Ward › Area. Properties and searches use them, and the field app filters assignments by ward. The 23 LGAs are fixed and their 255 wards, from INEC's directory, are loaded for you; you add areas.
- Open Locations and click an LGA. Its wards appear in the middle column.
- Type a ward name in the box at the bottom of the column and click Add.
- Click a ward to see and add its areas.
- Point at a name to rename (pencil) or delete (bin, click twice). A place used by any property or project cannot be deleted.
To add many at once, use Import with the wards-and-areas template. Export downloads every LGA, ward and area. See Import and export.
Staff
Viewing needs users.view; changes need users.manage
Each person has a status:
| Status | Meaning |
|---|---|
| Invited | Invited but has not set a password yet. Cannot log in. |
| Active | Can log in and work. |
| Disabled | Access withdrawn. Their records and minutes stay. Can be enabled again. |
Invite a staff member
- On Staff, click Invite staff.
- Enter their full name, work email, phone (optional) and staff ID, and choose their role.
- Click Send invitation.
The next screen shows the one-time link. If email is set up it has been sent too; if not, copy the link and send it yourself. It works once and for 7 days.
- Email addresses and staff IDs must be unique.
- You cannot give anyone more access than you have. Only an Administrator can assign the Administrator role or change an administrator’s account.
- Field surveyors need the field app permission (survey.field). The default Field Surveyor role also has field.office: they can log in to the office app too, where they see and change only the properties (and their claimants) in the sub-boundaries assigned to them. A role with survey.field alone is for the phone only.
Manage a staff record
Click a person to open their record.
- New invitation link (for someone still Invited) replaces the old link; the old one stops working.
- Password reset link (for Active people) gives a link valid for 24 hours. Use it when someone forgot their password and email is not working.
- Edit changes name, phone, staff ID and role. You cannot change your own role.
- Disable access (click twice) blocks the person from their next request onward. You cannot disable yourself. Enable access reverses it.
Disable them rather than changing their email: their name stays on every minute they wrote. If they were a field surveyor, first reassign their open surveys (an officer can withdraw an assignment and assign it again).
Roles
Needs roles.manage
A role is a named set of permissions. Changes apply to everyone with the role at their next request — no need for them to log out.
Create or edit a role
- Click New role, or click an existing role.
- Give it a name and description.
- Tick the permissions. Ticking a group heading ticks the whole group.
- Click Save role.
- Administrator is locked: it always has every permission and cannot be edited or deleted.
- A role can only be deleted when nobody holds it. Move its staff to another role first.
- You cannot remove
roles.managefrom your own role (you would lock yourself out). - A role whose only permission is
survey.fieldis a field role: field app only, with 30-day sessions so it keeps working offline.
Every permission is listed in Roles and permissions.
Dictionaries
Needs dictionaries.manage
Administration › Dictionaries holds the lists the field and office forms use. There are two kinds:
| Kind | Built-in dictionaries | Used for |
|---|---|---|
| Choice lists | Property types, Land use, Structure types, Structure condition, Photo labels, Document categories, ID types, Banks | The options offered in dropdowns |
| Priced items | Economic trees, Crops, Building classification | What is found on a property and what it is worth: valuations are built from these rates |
Click a dictionary to open it. The Items tab lists its items in a tree, with their code, unit and rate, and how many properties use each one. Minutes records every change.
Edit a list
- Add item adds one. Give it a label; the code is made from the label if left blank, and cannot change later. The + on a row adds an item under it.
- The pencil changes the label, where it sits and its order in the list.
- Retire (click twice) takes an item out of use. Retired items stay on old records but can no longer be picked. Tick Show retired to see them, and Restore to bring one back.
- Items with a padlock are locked: the system itself uses them (for example the National ID (NIN) ID type, or the document categories the compensation steps ask for), so they cannot be retired.
- New dictionary creates your own list or priced dictionary, marked custom. Only custom dictionaries can be deleted.
Priced items and rates
Priced dictionaries are trees. Only the items at the bottom of the tree — with nothing under them — can be put on a property, so those carry a unit and a rate:
| Dictionary | Tree | Rate |
|---|---|---|
| Economic trees | Tree type › size: seedling, young, mature or old | Per tree |
| Crops | Crop | Per hectare |
| Building classification | Class › component › type | Per m², per metre or each |
A new installation starts with sample rates for testing. Replace them with the approved KADGIS compensation rate schedule before any real valuation.
- Click Rate… on the item.
- Enter the new rate (₦), the date it is in force from, and a reason or reference (for example the approval of the rate schedule).
- Click Save rate.
- A new rate closes the previous one. The rate history is kept and shown in the same dialog.
- Rates are a guide for valuers: a case’s lines show the rate in force when the case opened, as helper text beside the valuer’s own figure. No amount is ever filled in or added up from a rate.
- Only valuers (comp.valuate) and dictionary keepers (dictionaries.manage) see rates. Property items, the field app and other roles never show them.
Export and import a dictionary
In a dictionary, Export downloads its items and Import loads them from Excel or CSV (also needs data.export or data.import). The columns are Code, Label, Parent code, Unit, Rate, Active and Order. Existing codes are updated and new codes are added; a different rate starts a new rate from today. Export first to see the codes. See Import and export.
Tags
Administration → Tags (permission Define tags) holds the labels staff put on records: for example a Priority group with High and Low, a Risk group, or a single Revisit tag for the field teams.
- Group (optional) collects related tags. Tick Only one tag of this group per record and adding one (High) takes the other (Low) off.
- Can be put on limits which records the tag fits (properties, claimants, cases, projects…). None ticked means any record.
- Field agents may add it on the phone lets field agents set or clear the tag on properties they capture; other tags show on the phone but only the office changes them.
- A tag in use cannot be deleted: retire it (untick In use: hidden from pickers, kept on its records) or merge it into another tag (every record moves across, then it is deleted).
Staff with Add and remove tags tag records from the record's file (the chips under its heading, + Tag) or many at once (tick rows in a register, then Tags…). Registers filter by tag, the find box finds #tag, project maps colour parcels by tag, messages can go to claimants with a tag, and exports and imports carry a Tags column. Every change is minuted on the record.
Rules
Needs settings.manage
Administration › Rules holds the checks that keep one person from doing everything alone. They start off; each applies from the next step recorded, and every change is minuted on your staff record.
- The valuer does not approve their own case: whoever saved a case’s current valuation cannot approve it.
- A second approval above an amount (₦): a cash approval above it needs two different people, for the same amount.
- Collection confirmed with a code: Paid needs the six-digit code sent by SMS to the claimant’s phone, or a written reason (see Finance › Mark as paid). Needs SMS delivery set up (Termii).
- Cheques only from approved payment batches: a cheque is recorded only for a case in a payment batch that a second person has checked and approved (see Finance › Payment batches).
The census cut-off date is set on each project (Officer › The census cut-off date). Work queues › Integrity still lists a valuation approved by its own valuer, for anything recorded before the rule was on.
AI suggestions
Needs ai.manage
Administration › AI controls where the system may ask a language model for a suggestion. AI only suggests: staff accept, edit or dismiss each one, and accepted ones are minuted. See AI suggestions for what each feature sends and the data-protection checklist to complete first.
- The IT operator sets
AI_ENABLED=trueand the keys (OPENROUTER_API_KEY,OLLAMA_API_KEY) on the server, and default models (AI_OPENROUTER_MODEL,AI_OLLAMA_MODEL). Until then the page says AI is not set up. - Under Providers, run a Test call for each provider with the model you mean to use: it reports OK and the time, or the provider’s error.
- Under All features, set the daily and monthly caps (USD), and tick AI suggestions on. Leave Read ID cards and land documents off unless the data-protection checklist covers it.
- Switch on the features you want, one by one. Models sets a feature’s models in fallback order (up to three) and its own caps; empty uses the server’s defaults.
- The feature table shows, for each feature, what it sends, what it cost today and this month, its calls and failures over 7 days, the average time, and how often staff accepted its suggestions.
- Calls lists every call — person, feature, model, result, identifiers removed, tokens, cost, time, accepted or dismissed — with filters. No request or answer text is kept, unless Keep redacted request and answer text is ticked for troubleshooting (cleared after 7 days).
- When a cap is reached the features stop with a clear message until the next day or month, or until you raise the cap.
- Offer Hausa drafts shows Hausa versions of message drafts. Tick it only once a Hausa speaker has checked them (
npm run ai:eval message_draftwith the real model). - Every change on this page is minuted on your staff record.
Reports and overnight reports
Needs reports.view to write reports; reports.manage to schedule them
Outreach › Reports writes progress, management and RAP status reports from the register’s figures (see Finance › Reports for writing, checking and printing one). Under Overnight reports:
- Schedule a report: the template, the project (or every active project), and who is emailed when a draft is ready. Weekly reports are made every week, monthly and RAP ones each new month, between 01:00 and 05:00.
- You are the author of a scheduled report: it is drafted with AI only when the Report narrative feature is on and your role has
ai.use, otherwise plainly. It stays a draft until someone checks it and marks it final. - Make it now makes one straight away (to try a schedule); Pause and Delete stop it. Only staff who may read reports can be emailed.
- Reports, their changes, finalising and emailing are minuted on the report; schedules on the schedule.
Background jobs
Needs jobs.manage
Administration › Background jobs lists the work the server does in the background:
| Job | Queued when |
|---|---|
| Project map scan | A project boundary is saved, or Run again is clicked on its Map tab. It keeps roads, rivers, water, landuse, buildings and power lines as shapes; a project over the scan limit (SCAN_MAX_AREA_KM2, 150 km² by default) fails at once, without retries |
| Spatial check: property | A property boundary changes |
| Spatial check: project | A project boundary changes, or Check again is clicked on its Map tab. All the project’s properties are checked together in a few seconds, also those known only by a GPS point |
| Nightly spatial re-check | Every night, over all boundaries |
| Sub-boundaries: refresh | A sub-boundary’s outline, status or overlap setting changes, or the project boundary changes: colours, crossings, and which properties lie in which area |
| Sub-boundaries: membership | A property boundary changes in a project that has sub-boundaries |
| Sub-boundaries: automatic division | Generate automatically… on a project’s Sub-boundaries tab. It is not retried: a failure says why on the tab |
| Nightly sub-boundary re-check | Every night, for every project with sub-boundaries |
| AI log: clear old debug text | Daily: removes the troubleshooting text of AI calls older than 7 days (only kept when that switch is on) |
- Each job is Queued, Running, Done or Failed. Click one to see when it ran, its attempts, its input and its result or error.
- A failed job is retried a few times on its own. Once the cause is fixed (for example the map data server was unreachable), open it and click Retry now.
Email and SMS delivery settings
Needs settings.manage
Messages › Delivery settings shows which service each part of the system is using. Your IT operator sets them on the server; here you can check them.
| Shows | Meaning |
|---|---|
| smtp / termii | Email / SMS really goes out. |
| console · not sending | Nothing goes out: messages are only printed in the server log. Invitations and reset links must be passed on by hand. Ask your IT operator to configure the service. |
| test mode · not sending (identity & bank checks) | Bank, BVN and NIN checks use the built-in test rules, not Monnify. Results are not real. |
- Check connections logs in to the mail server and opens the storage bucket without sending anything.
- Send a test sends one email or SMS to an address or number you type.
The outbox
Messages › Outbox lists every email and SMS the system has sent — invitations, password resets, claimant messages and tests — with its status and the provider’s reference. Click one to read it, including any link. It is only available when the IT operator has turned it on (OUTBOX_VIEWER_ENABLED).
The outbox shows invitation and reset links. Anyone who can see it could use a link that has not been used yet, so only give settings.manage to people who need it.
Good habits
- Give each person the smallest role that lets them do their job. Use Viewer / Auditor for read-only access.
- Keep at least two active administrators, so one can recover the other’s account.
- Review the Staff list monthly: disable people who have left and resend links to anyone stuck as Invited.
- Do not share accounts. Every minute names the person who did it.