Services as configuration

On the Pamodzi e-Services framework a new service is designed, not programmed. An MDA's service designer builds it in the back office from a few parts. This lesson explains those parts, how a change to a service is controlled, and when code is genuinely needed.

The parts of a service

Part	What it holds	Who sees it
Service passport	Name, description, who can apply, eligibility, processing time, validity of the document issued, legal references	Citizens, before they apply
Application form	The questions, their validation rules, and which answers depend on others	Citizens when applying; officers when reviewing
Required documents	The supporting documents an applicant must upload, and which are optional	Citizens and officers
Fees	A fee, or a schedule of fee lines, and the revenue code the money is posted to	Citizens before submitting; finance
Process	The workflow: an ordered set of steps, each assigned to one or more roles	Officers
Output templates	The certificate, licence, permit or letter the service issues, with its fields	Citizens (the issued document) and anyone verifying it
Notifications	Which events send an SMS or e-mail, with editable wording	Citizens and officers

Everything specific to a service lives in this configuration. The portal shows it from data: there is no hard-coded page for any service.

Forms

Forms are built in a visual form builder. Fields can be validated against a national register (for example, "this company number must exist in the business register"), can show or hide depending on other answers, and can use platform field types such as a geometry field for an area on a map.

Each application is tied to the form version it was made on, so a later change to the form never changes the meaning of an application already submitted.

Processes and step types

The process designer arranges steps. Each step has a type and names the roles that may perform it. Typical step types include:

review an application;
inspect a site (checklist, GPS location, photographs);
approve, or record an executive decision;
generate an invoice or fee, make a payment, verify a payment;
book an appointment with the applicant;
generate an output document, hand over a document, notify the client.

Step gates enforce the real-world order. A case cannot leave an inspection step until the findings are recorded, and cannot close while a paper document is still waiting to be handed over. Assigning a case or adding a note is an edit, not an advance, so a case is never moved forward by accident. Each step has a service-level clock derived from the published processing time.

Fees and money

A service can charge a single fee or a schedule of lines, and each fee is posted to the service's own Treasury revenue code. Citizens see the fee before they submit. Part payments are supported: a part-paid invoice stays pending, so nothing treats half a fee as paid. Refunds and voided receipts need a reason; receipts are never deleted.

Output documents

Output templates are Word-style documents with placeholders (for example ${ApplicantName} or ${PermitNumber}) filled from the application and the platform. When a document is issued it is sealed by the platform's signing service and carries a QR code that leads to the verification page.

Two rules always apply:

A document is never issued as if it were sealed when sealing failed.
Verification never overstates validity: an expired, suspended or revoked document is shown as such.

Changing a live service: versions and maker-checker

A service is versioned. By default (SERVICE_MAKER_CHECKER on), an edit does not go live at once:

The designer edits a draft version of the service.
The draft is submitted for approval.
A second person approves it, and it is published (or scheduled for a later date).
The previous version becomes superseded and can be rolled back to.

A version snapshot covers everything a citizen or the case engine sees: passport, form, process, fees and revenue code, required and output documents. Turning maker-checker off is an emergency switch, not a way of working.

The AI service builder

The back office includes an AI service builder. An officer uploads the governing Act, Statutory Instrument or a service charter, and the builder drafts:

the service passport, form and process;
optionally, the output-document templates (certificate, approval and rejection letters, acknowledgement, payment
notice), each clause with a citation of the section it comes from.

The draft is a starting point. An officer reviews and corrects it before it is used, and it then follows the same version and approval rules as any other change. Placeholders the AI invents that are not real form or system fields are removed and reported. The AI features are switched off by default, and each one is enabled separately.

When is code needed?

Code is written only when a genuinely new capability is missing, and then it is built generically. Ask:

Question	If yes
Can the form, process, fees, documents and templates express it?	Configure it. No code
Could more than one MDA use this capability (selling goods, quotas, inspections, a map area)?	Build a reusable capability in core, switched on per service by a setting
Is it truly specific to one MDA (for example a ministry's estate register)?	Build a module (lesson 5)

Example

An MDA wants a new "Example Event Permit". It needs a form, an inspection, a fee, an approval and a permit. All of these are existing parts: no code is needed. A second MDA wants applicants to draw the event area on a map. The geometry field already exists as a generic capability, so this too is configuration. If the second MDA needed its own fee rule based on a register only it holds, that rule would go into a module through the payment.quote extension point, not into core.

How a service is proven

A service is not "done" until:

its end-to-end test passes on both seed profiles (and in federated topology when the service can live on a node);
its documentation, with screenshots, is generated by that run;
the service status list has been regenerated and shows its five checks.

Lesson 6 covers this in detail.

Check your understanding

Name four parts of a service that a designer configures in the back office.
Why is an application tied to the form version it was made on?
What happens between a designer's edit and a citizen seeing the change, when maker-checker is on?
What must an officer do with a draft produced by the AI service builder?
When would a new feature become a reusable capability rather than a module?