Define customer portal requirements before drawing screens

Start with the service boundary, not a dashboard

Write the portal’s job in terms of a customer task. “A customer can see the current status of an accepted request and provide a requested document” is testable. “Give customers a modern dashboard” leaves the records, permissions and business response undefined. Name the problem that the portal removes, such as status requests arriving in several inboxes or documents being exchanged without a reliable link to the right case.

Decide which part of the service remains outside the portal. A first release may show approved requests but keep quotations in an existing accounting system. It may accept supporting files but leave final approval with a staff member. Record those boundaries so an attractive screen does not quietly become a promise to replace every internal tool. Link each customer-facing state to the staff process that makes it accurate.

Complete this first-release requirements sheet

Use one row per important task, then review the sheet with the people who serve customers and maintain records. A requirement is incomplete when it names a button but not the record affected, the allowed user, the resulting state or the person who handles an exception.

• Users: Which customer, colleague, administrator or external partner uses the portal, and how is each account created, verified, suspended and closed?
• Records: Which requests, projects, documents, messages or profile details appear, and which system is the authoritative source for each?
• Actions: What may each role view, add, change, download or withdraw? What requires staff review before it takes effect?
• Permissions: How is access checked for every record and action? What must never be inferred from a hidden link or a page identifier?
• Notifications: Which event warrants a message, which channel is used, and can the recipient act without exposing sensitive information in the message?
• Exceptions: What happens when a record is missing, access has expired, a file is rejected or two people change the same item?
• Ownership: Who corrects data, answers access questions, reviews logs and decides whether a portal feature is still accurate?

Define access for every role and record

Create a role-and-action matrix instead of scattering permission notes across mockups. OWASP recommends denying access by default, checking permission on every request and preferring rules based on attributes and relationships when simple roles cannot express the boundary. In practical terms, a signed-in customer should see a request because it belongs to their account, not merely because they know its address. A staff role should receive only the access needed for its work.

Describe identity recovery as part of the journey. Decide what evidence is needed when someone loses access, changes organisation or asks to add a colleague. NIST’s digital identity guidance separates identity proofing, authentication and federation; your portal may not need the highest assurance level, but it does need a proportionate, documented choice. Include session expiry, multi-factor authentication where appropriate, account suspension and a way to revoke access without deleting the underlying business record.

Hypothetical example: a maintenance request portal

Consider a hypothetical equipment-maintenance company. Its first portal release lets an authorised customer contact view accepted service requests, see one of four plain-language statuses, download the engineer’s completion note and add a requested photograph. Office staff can correct a status and reject an unsupported file type. Engineers continue using the existing scheduling system; the portal reads only the status needed by the customer.

The journey starts from an invitation sent after a request is accepted. A customer signs in, opens a request that belongs to their organisation and sees the last update time and responsible office contact. If a photograph fails validation, the page keeps the request visible, explains the permitted format and offers a retry. If the scheduling connection is unavailable, the portal shows the last confirmed status with its timestamp and routes the issue to staff. This is a hypothetical planning example, not a Kinetivy client result.

Write the empty, error and waiting states

A portal journey includes more than its successful state. Specify what a new customer sees before any records exist, how a pending change is distinguished from an approved one and what happens after a session expires. Avoid a generic “Something went wrong” when the user can take a safe next step. Preserve entered information when possible and never show another customer’s record while resolving an error.

Forms need visible labels, instructions placed before they are needed and errors that identify the affected field. W3C’s form guidance also recommends stating required formats and overall instructions clearly. Explain uploads before the file chooser: accepted types, size limits, purpose and who can view the file. Confirm an action only after the backend has accepted it, and give the customer a stable reference they can use if staff help is needed.

Review the requirements before design begins

Walk through one normal journey and at least three exceptions using sample records. Ask the customer-facing owner to explain what staff do after each action. Ask the technical reviewer to identify the source of every displayed status and the authorization check behind every action. Remove features that lack a reliable record, owner or recovery path. The resulting sheet becomes an input to scope and design; it is not a substitute for later acceptance testing.

• Each first-release action has a named user, record, permission rule, resulting state and staff owner.
• Customer-visible labels use service language and distinguish current, pending, rejected and unavailable states.
• Invitation, sign-in, recovery, suspension and account closure have documented paths.
• Notifications reveal no unnecessary record details and link only to authorized views.
• Empty, invalid, offline and conflicting-update cases have a safe customer message and staff route.
• The team can identify the source, update time and owner of every customer-visible status.