Designing a service

On the Pamodzi platform a new e-Service should need no new code. A service is a set of configuration that an MDA designs in its own back office: an application form, a process, fees, required documents and output templates. Code is written only when a genuinely new capability is missing, and then it is built generically so that every ministry can use it.

This guide walks through each part of a service, how a change is published, how the national portal receives it, and what makes a service complete. The course Service designer covers the same ground with exercises and a certificate.

Where services are designed

Services live in the back office under Service Management → Manage Services. Each service opens in the service editor, which has one tab per part:

Tab	What you set
Service settings	Name, providing MDA, type (public or internal), status, description, who can apply, the fee text shown to citizens, processing time, validity, legal references
Form builder	The application form (form-js), standard government fields, register look-ups, a separate form per case type
Service process	The steps a case follows from submission to completion, and the role that does each
Supporting documents	The documents the applicant uploads, required or optional
Output documents	Word (.docx) templates for certificates, licences and letters
Transaction codes	The revenue code used when posting the service's revenue
Fees	Fee type, fee schedule, case types, finance approval
Versions and approval	Drafts, checks, test submissions, submission for approval, version history
Change history	Who changed what, and when

The service editor is for service administrators. The server decides who may change a service: hiding a button is never the authorisation.

Ways to start a service

By hand. Manage Services → Create service. You fill each tab yourself.
From a ready-made design. Service Management → Ready-made services (administrators). The first design is event
registration (capacity, fee, approval, attendee list). The result is an ordinary draft service that you finish in the editor.
With the AI Service Builder. Manage Services → AI Service Builder (administrators only, shown only while the AI
feature is switched on and within budget). You upload the statutory instrument or Act (PDF, Word or text, at most 10 MB). The assistant drafts the form, the process, the fees and the service passport, and can also draft output document templates. Everything it produces is saved as a draft: a person reviews it and another administrator approves it before it goes live. If the assistant cannot design a workflow from the document, a standard workflow is used and the page tells you to check the steps.
By import. The services of the legacy catalogue were imported with the backend's importer. Imported services
are ordinary services and are edited in the same editor.

The parts of a service

Service settings

These details make up the public service passport: what the service is, who can apply, how long it takes, how long the result is valid and which law it rests on. A public service appears on the national portal; an internal service is visible only to officers. An inactive service is hidden from applicants.

The fee text on this tab is only what citizens read. The amount actually charged comes from the Fees tab.

Application form

The form builder uses form-js. Drag fields from the palette and set their properties. Guidance:

Use the field library for standard government data. Service Management → Field library holds definitions such as
NRC number, TPIN, PACRA registration number, Zambian phone number, e-mail, plot number, vehicle registration, passport number, date of birth, province and district. Each carries its own check, error message and example. The server checks every library field with the version the form pinned, so the rule applies to the portal, the API and the POS alike. New library versions are published by a second administrator.
Use the geometry field ("Location / area on map") when the applicant must mark a point or draw an area. The map
loads only when the applicant opens it.
Give a case type its own form when, for example, a renewal asks different questions from a new application.
Collect the minimum. Ask only what the decision needs (Data Protection Act No. 3 of 2021).

Process

The process designer offers a library of step types. Each step names the role that performs it:

Kind	Step types
Applicant	Fill e-Service Form, Make Payment
Officer	Review Application, Inspect Site, Approve, Executive Decision, Generate Invoice / Fees, Verify Payment, Appointment with the Applicant, Hand Over Document, Parallel approval, Hearing, Instalments to another party
Automated	Notify Client, Generate Output Document, Decide route (conditions on answers, fee or case, with a default path), Wait / notice period

A switched-on module can add step types of its own; they appear in the palette only while the module is on. For each step you can also choose where the case goes next, who gets it (rules by condition, with a default officer or office), what officers may do at that step, whether another ministry performs it, and which office handles it.

Use Check and try the process on the Service process tab to validate the draft, simulate it with sample answers (which decide the routes and due dates) and compare it with the live process.

Fees

Fixed: one amount, invoiced automatically.
Dynamic: an officer (Case Officer or Supervisor) adds the fee while processing. Pair it with a
Generate Invoice / Fees step.
Module fee types appear when the module that provides them is on (for example a fee worked out from a register).

The fee schedule holds the lines. One fixed line prices the case automatically at submission; lines tied to a case type are charged when the applicant chooses that type; several lines let the officer pick the right one at Generate Payment. You can require finance to approve fees worked out by officers before they are invoiced. Every fee change is kept in the fee change history.

Required documents

List each document with a name, whether it is required, and short guidance ("certified copy, not older than 3 months"). A document can apply only to some case types. Required documents block submission until uploaded. Officers verify or reject each upload.

Output documents

Each output document is a scenario (for example "Approval letter" or "Licence") with a Word template. Templates use placeholders such as ${ApplicantName} that match form field keys, plus date formats, QR codes, conditional blocks (${#if X} ... ${/if}) and repeated rows (${#each X} ... ${/each}). A Generate Output Document step issues the document. Fields that the office, not the applicant, must supply are entered on the case's Certificate particulars tab before issue.

Issued documents are sealed with the platform's electronic seal and carry a QR code for public verification. A document is never presented as sealed when sealing failed.

Capabilities

A capability says what kind of service it is, so the interfaces act on the service's nature rather than its identity. Core capabilities include goods-sale (goods sold and collected, no decision), no-decision, account-payment (a payment against an account the citizen already holds), lease, ati-request and verified-identity (the applicant needs an NRC verified against the national register). Modules declare further capabilities, usable only while the module is on for that ministry.

Prefer reusable capabilities over one-off modules: the shop, the allocation and quota ledger, name reservation, inspections, enforcement cases and the geometry field all serve any ministry. Today a capability is usually recorded on the service by a module's service set-up script rather than in the editor.

Versions and publishing

With versioned publishing on (the default), saving writes to a draft version, never to the live service.

Draft. Edit freely. The Test submission panel runs the draft as if you were an applicant ("Test only -
nothing is saved or sent") at phone, tablet or desktop width, and lets you walk the case through its steps.
Submit for approval with a change summary. The platform first runs checks: form errors block the submission;
warnings are kept for the approver. The impact view lists applications in progress, removed or retyped fields, and asks what to do about fields that became required (apply to new applications only, flag existing ones, or backfill). Breaking changes are refused.
Approve. Another administrator, who did not make, edit or submit the version, approves or rejects it with a
reason. Approval can be scheduled with "Publish at".
Published. The version becomes live. The previous one is superseded; a rollback publishes a copy of an older
version as a new one.

Applications already in progress stay on the version they were made under. A brand-new service starts switched off with a draft version 1, so nothing reaches citizens until someone else approves it.

Federation of the catalogue

Each MDA may run its own back office (a node); there is one national portal (the hub). A service is always designed and published on its owner's back office, never on the hub.

When a version is published on a node, the node signs a manifest of the public service data and pushes it to the hub
right after the change commits. The hub checks the signature and that the sender owns the service.
Drafts never leave the node.
If a push is missed, the hub pulls changes from each node every 15 minutes.
The hub shows a node's service read-only and refuses any edit (409 SERVICE_MANAGED_BY_NODE).
Internal settings (templates, assignment rules, revenue settings) are not in the manifest. Answers, notes and
documents stay on the node.

System administration → National catalogue sync shows, on the hub, each node's services and how long a publish took to reach the portal, and on a node, what is still to be delivered. The federation contract itself is described in Federation: hub and nodes; when a genuinely new capability is needed, see Building modules.

Checklist: a complete service

Service settings complete: purpose, who can apply, processing time, validity, legal references.
Form uses field-library fields for standard data and asks only what is needed.
Every step of the process names its role; automated steps are configured.
Fees set and tested, including each case type.
Required documents listed with guidance.
Output templates uploaded; every placeholder is filled by a form field or the Certificate particulars tab.
Capabilities and any module the service needs are switched on for the ministry.
A test submission walked through every step.
Version approved by a second administrator.
End-to-end test passes on both seed profiles (and federated, if the service can live on a node). See
End-to-end testing.
Documentation generated and published to the central documentation share. See
Service documentation.