A customer portal should do more than store information. It should explain what a user can do with it. A label such as “in progress” might mean a request was received, somebody is working on it or staff are waiting for missing information. Combining those meanings leaves customers calling for updates and employees explaining the actual situation outside the portal.
This guide uses a fictional installation company managing enquiries, proposals and appointments. The situations are illustrative rather than a delivered customer project. Develop a state model connected to events and responsibilities. The goal is not the largest possible collection of labels, but an explainable route where users understand what is confirmed, what remains uncertain and who needs to take the next step. That model should remain useful when a normal process is interrupted.
Start with the questions users ask
Ask what customers and staff currently want to know. Did the request arrive, is information missing, does a proposal remain valid, or is an appointment genuinely confirmed? These questions may require different records and events. A simple timeline may help more than one summary label that hides detail and becomes understandable only after a telephone conversation with somebody inside the organisation.
Follow one enquiry in the fictional installation company from submission to completion. Record where responsibility changes. The customer provides information, an employee assesses the situation and a planner proposes an arrangement. Some activities may run alongside each other. Make those relationships understandable before deciding which labels, colours or badges the portal needs to communicate the process. The interface should reflect the work rather than define it accidentally.
Define each state through a verifiable event
State what must be true before a label appears. “Received” may mean that a request is stored under a stable reference. “Reviewed” might mean an authorised person examined a particular version. “Appointment confirmed” can require a recorded confirmation operation. Do not make those events depend only on somebody opening a screen, since viewing information and completing a business decision are different activities.
Also identify who may cause the transition and which information accompanies it. Preparing a proposal does not establish customer acceptance. A background process attempting to send a message does not prove the recipient agreed to the arrangement. Explicit transitions let the organisation investigate why a state belongs to a particular record instead of reconstructing meaning from whichever screen happens to display it now.
Separate internal work from customer-facing progress
Internal activities need not map one-to-one onto customer labels. A technical queue, draft note or internal review task may help staff while confusing customers. Decide what customers need to understand their next step and which details handlers use to organise work or investigate an interruption. A simplified view can be useful when it preserves the underlying business meaning.
For example, a customer might see that supplementary information is being assessed and when another response is expected under the genuinely agreed working method. A handler may additionally see a missing check on one document. Avoid reassuring labels that conceal a real blockage. A simple presentation should summarise the situation, rather than suggest more favourable progress than the recorded events actually support.
When several systems influence a status, define which source has authority: Synchronise data without uncontrolled overwriting.
Give waiting an owner and a next action
A waiting state is useful only if it identifies who or what is being waited for. Missing customer information calls for a focused question. Internal review needs a responsible role. An external dependency needs an investigable reference and follow-up arrangement. Avoid an indefinite state where every participant assumes that somebody else has already taken responsibility for resolving the outstanding issue.
Describe what happens when a response never arrives or does not answer the question. An automated reminder may help without resolving substantive uncertainty. Give staff an overview of decisions awaiting attention and show customers which operation moves their request forward. The route can deliberately be manual. The important point is that the next step remains visible instead of disappearing between applications, teams and individual inboxes.
Connect confirmation with the content reviewed
Confirmation concerns a particular arrangement or document version. Record what the user saw and which operation they confirmed. If the date, commercial content or scope changes afterwards, assess whether another approval is needed. An old check mark must not silently become evidence for a materially different arrangement added to the record after the person made their original decision.
OWASP discusses the relationship between transaction review and execution. Apply that principle deliberately to consequential portal actions. In the fictional example, a customer confirms a proposal for a specific time window. A subsequent planner change creates a newly reviewable state. The customer and relevant parties determine the business arrangement; the application needs to record the selected meaning consistently and show which content a particular confirmation actually concerns.
Keep notifications separate from work state
An email, alert or text message asks for attention. It is not automatically proof that underlying work was completed. Distinguish a stored request, an attempted notification and a confirmed appointment. A message failure need not undo the saved enquiry; the application may need a separate route for informing the user again. Conflating those events can make both recovery and customer communication harder.
Consider repeated messages too. Another email must not silently create another request or confirmation. Retain the same business reference where appropriate and explain which notification belongs to which event. Support can then explain the process without relying on email counts. Forwarding, filters and delayed delivery can give a mailbox a different apparent history from the actual operations recorded in the application.
Represent external uncertainty accurately
A connected planning service may be temporarily unavailable. The portal should distinguish last-known information from a currently confirmed state. Explain what is being investigated and which operation the user can reasonably perform next. No response is not the same as a definitive rejection; a locally saved request is not the same as a confirmed change in the other application.
Include an uncertain outcome in design: the planner may have saved the change while confirmation was lost. An additional state or internal investigation task can prevent blind repetition. Identify who resolves uncertainty and how the eventual outcome is associated with the enquiry. Restoring the technical connection alone does not establish the business position. Staff need enough information to reconcile what happened during the interruption.
Select straightforward operational indicators
Measure where users get stuck and which pending states remain open. Define the beginning and end of each measurement. Time between submission and first substantive review differs from time until a final appointment. Use the same definition when comparing before and after a change; otherwise an apparent improvement may mainly reflect a different measurement rather than a better working process.
Google SRE distinguishes observed indicators from objectives selected for them. Apply that thinking proportionately to the portal. A summary can expose backlog while an average hides a few very old enquiries. Combine an overview with records needing attention. Choose thresholds from the agreed service and operating capacity, rather than assuming every process needs the same dashboard measures or that one attractive metric captures the customer’s experience.
Test explanations through normal and unusual progress
Ask a user to explain the next step from fictional records without extra spoken guidance. Include an ordinary enquiry, missing information, a revised proposal and an unconfirmed external response. Also check that the appropriate role can make the transition and that an old or duplicate operation does not advance the state unintentionally. Understanding and technical behaviour should support the same intended working rule.
Retain label meanings, transition rules and trial cases at handover. When a later change merges or renames a state, examine filters, notifications, reporting and existing records too. A small text change can conceal a substantive process change. Preserving meaning keeps the portal explainable for customers, support staff and another developer who needs to understand how the same progression is recorded and presented.
Turn the explanation into a project decision
Record your assumptions, unknowns and acceptance checks in the matching tool. Use the service guides to discuss delivery and scope.
Open the preparation tool ↗Questions about this topic
How many states does a customer portal need?
Enough to explain relevant responsibility and next actions. Begin with important events and add a distinction only when it helps someone act or assess an outcome. A long state list without clear meaning does not automatically make a process more transparent or useful.
Can a state change automatically?
Yes, where the underlying event can be established and the transition fits agreed rules. Investigate exceptions, repeated processing and changes during review. An automatic route should preserve the same business meaning as an equivalent transition made by an authorised person.
Should customers see every technical error?
Not necessarily. Explain what the issue means for them and which next step is available. Technical details can remain with authorised staff. Avoid both incomprehensible error codes and a general success message when a consequential outcome is still unconfirmed or awaiting investigation.
Continue with a related question
Customer portal roles and permissions: who may use which record?
Define portal access by organisation, record, operation and field, including invitations, downloads, role changes and meaningful denial tests.
Custom software & portalsDefine custom software scope: turn a wish list into a usable first release
Prepare a bounded software assignment with users, information, states, exceptions, acceptance evidence and explicit extension boundaries.
Custom software & portalsAccept custom software: assess complete tasks and agreed boundaries
Prepare software acceptance with representative users, input, exceptions, access, recovery evidence and an explicit decision about unresolved findings.
APIs & integrationsSynchronise data without uncontrolled overwriting
Assign field ownership, recognise competing changes and design explicit rules for versions, empty values, archiving and recovery.
Sources and technical background
- OWASP: Transaction Authorization Cheat Sheet ↗
Considerations for connecting the reviewed operation to the transaction actually executed.
- Google SRE: Service Level Objectives ↗
The distinction between measurable service indicators and agreed objectives; selected examples and thresholds are illustrative.