Designing the application form
The application form is what the citizen fills in on the national portal (and what an officer fills in at a counter or on a POS terminal). A good form asks only what the decision needs, checks answers as they are typed, and gives clear error messages.
The form builder
Open the service and go to Form builder. The builder is form-js, a drag-and-drop designer:
- the palette on the left holds the field types: text, number, select, radio, checklist, checkbox, text area,
date, groups and more;
- the canvas in the middle shows the form;
- the properties panel on the right sets the selected field's label, key, description, whether it is required,
and its validation.
Every field has a key. The key is how the answer is stored and how output templates and process conditions refer to it, so choose short, stable keys such as business_name or plot_number. Changing a key later breaks templates and conditions that use it.
Use the field library for standard data
Standard government data should not be designed again for every service. Service Management → Field library holds standard field definitions, each with its rule, an instructional error message and an example. The built-in ones include:
| Field | Checks |
|---|---|
| NRC number | The NRC pattern, for example 000000/00/0 |
| TPIN | 10 digits |
| PACRA registration number | The registration number format |
| Zambian phone number | A valid number, stored as +260... |
| A valid address | |
| Plot number, vehicle registration, passport number | Their formats |
| Date of birth | A real date, not in the future |
| Province, district | Chosen from the code list |
In the form builder, the government fields picker beside the canvas inserts a library field into the form. The form records which library version it uses. The server then checks every answer to that field with the pinned version's rule, whether the application comes from the portal, the API or a POS terminal. That is why library fields are safer than a pattern typed by hand into one form.
A new library field, or a new version of one, is published by a second administrator. The library page shows where each field is used and has a Test a value box to try the rule.
Case types
Many services have variants: New, Renewal, Amendment. You define case types on the Fees tab. On the Form builder tab, the case type picker lets you:
- keep one form for every type (the service form), or
- give a type its own form, when a renewal asks different questions from a new application.
Case types also decide which fee line applies and which documents are required, as later lessons show.
The geometry field
When the applicant must show a place or an area (a plot, a borehole, a concession), use the geometry field, "Location / area on map". The applicant marks a point or draws an area. The map is loaded only when the applicant opens it, so the form stays fast on a slow mobile connection. Modules can add validators for geometry, for example a check that an area does not overlap an existing licence.
Looking up registers
The register look-up panel under the builder binds a form field to a national data register:
- a small register (up to 3,000 rows) becomes a searchable list whose options come from the register;
- a larger register (vehicles, registered companies) becomes a text field whose answer is checked against the register
when the application is sent.
Use it so applicants choose or confirm a real registered value instead of typing one that may not exist.
Conditional questions
form-js lets a field show only when another answer has a given value: ask for the "Previous permit number" only when the case type is Renewal. Keep conditions simple and test them (lesson 6 shows how).
Writing good questions
- Collect the minimum. The Data Protection Act No. 3 of 2021 requires it, and short forms are completed more often.
If no officer uses an answer to decide, do not ask for it.
- Plain English labels. "Business name", not "Name of Enterprise (as per Certificate)". Put guidance in the field's
description.
- Mark only what is truly required as required. Required fields block submission.
- Use the right type. A date picker for dates, a select for a fixed list, a number for numbers.
- Think of 375 px. Most citizens apply on a phone. Long tables and wide groups are hard to use on a small screen.
- Never ask for secrets such as passwords or PINs.
A worked example
For the "Example Vendor Permit":
| Label | Key | Type | Notes |
|---|---|---|---|
| Business name | business_name | Text | Required |
| TPIN | from the library | Library field | Required; the server checks 10 digits |
| Phone number | from the library | Library field | Stored as +260... |
| Trading site | trading_site | Geometry | A point on the map |
| Goods sold | goods_sold | Checklist | From a fixed list |
| Previous permit number | previous_permit | Text | Shown only for Renewal |
Test it with synthetic values only: business "Example Traders", TPIN 1000000000, phone +260970000000.
What happens when the form changes later
A form change is part of a new version of the service. Before it can be submitted, the platform checks the form for errors. The impact view lists applications in progress and, for a field that becomes required, asks whether the rule applies to new applications only, flags existing ones, or backfills a value. Applications already in progress keep the form version they were made under. Lesson 6 covers this.
Check your understanding
- Why should you choose field keys carefully, and keep them stable?
- What does the server do with an answer to a field taken from the field library?
- When would you give a case type its own form?
- Which field type lets an applicant mark a place or draw an area, and when is its map loaded?
- Name three rules for writing good questions.
- What happens to an application already in progress when the form changes?
Sign in to record your progress.
Previous: Services are configuration Next: Modelling the process