Customer portal requirements: a worksheet for a B2B client or customer portal
Most portal projects go wrong in the requirements, long before anyone writes code. This worksheet turns "our customers need a portal" into a list that any builder can quote from.
By David, The Goodstack Company.
What a customer portal requirements list has to answer
A portal project usually starts as one sentence. Our customers need a portal. Everything that decides the cost is hidden inside it. Who signs in. What they are allowed to do once they are in. Which system holds the truth for each field on the screen. What happens when a request gets declined.
This page is a worksheet. Fill it in before you talk to any builder, including us. It works the same whether you configure the portal your CRM already includes, buy packaged client portal software, or commission a custom build. Anyone who reads a filled-in copy can quote from it.
Set aside an afternoon with one person who knows the customer process and one who knows the systems.
Step 1: list every role that signs in
Write one line per role. A role is what someone is allowed to see and do, so two job titles with identical access are one role, and one job title with two levels of access is two roles.
A B2B customer portal usually has more roles than expected:
- The customer's everyday user, who raises requests for their own site or team
- The customer's administrator, who sees everything their company has open and adds colleagues
- Partners or vendors, if they sign in to the same system
- Your staff who approve or fulfil what comes in
- Your staff who pick up exceptions
- Your administrator, who grants and removes access
For each role, write down how many people it covers today and where their identity lives. If your customers already sign in to something of yours, say so. Identity changes the shape of a build early.
Step 2: one line per action
This is the heart of the worksheet. Write a row for every action a role needs, in the wording your customers use.
| Column | What to write in it |
|---|---|
| Role | Who does this |
| Action | The thing they are trying to finish, in their words |
| See or do | Whether the screen displays data or changes a record |
| Source system | Which system holds the truth for this data today |
| Approval | Who approves it, and on what rule |
| Write-back | Which record changes when it is approved |
| Failure | What should happen when it is declined or fails |
| Frequency | Roughly how often this happens today |
Two columns do most of the work. "See or do" separates a screen that reports a status from one that finishes a piece of work. "Source system" catches actions that need data from two places, which are usually the expensive ones.
Count the rows when you are done. If almost all of them say see, the portal you already own may be close enough. Our comparison of Experience Cloud and a custom portal walks through that decision role by role.
Step 3: name the system of record for each field
Go through your rows and ask where each piece of data lives now. Orders in the ERP. Cases in the CRM. Invoices in accounting. Documents in a file store. Entitlements in a spreadsheet one person maintains.
Two answers matter most.
- A field with two sources. Two systems hold a version of the same value and nobody has decided which one wins. Decide it now, on paper. Every project that skips this decides it later, under pressure, during testing.
- A field with no system. It lives in an inbox or in somebody's head. That field needs an owner and a home before a portal can show it to a customer.
For each system, note whether an API exists, who administers it, and whether your current plan or edition includes API access. Check the vendor's current documentation for that last one, since it changes between editions and releases.
Step 4: write the permission rule for each action
Role alone is rarely enough in B2B. Access usually depends on the account too: this person, at this company, can see these records and change those ones. Write that rule as a plain sentence for every row.
Then write down the controls your security reviewer will ask about:
- How people sign in: single sign-on, or email and password with multi-factor authentication
- How long a session lasts and what happens to an idle one
- Whether one customer's data can ever be reached from another customer's session, and how that gets tested
- What is written to an audit log, who can read it, and how long it is kept
- Where the data is hosted, and what the hosting provider publishes about its own controls
- Signing, if documents are signed, and whether identity verification is required
If a regulation governs who may handle your data, write it at the top of the sheet. It changes who is allowed to build the thing, and it is cheaper to know on day one.
Step 5: decide what happens when something fails
Most portals get specified for the path where everything works. The requests that eat your staff's time are the other ones. An approval is declined. A payment bounces. A document is missing. The source system rejects the update.
For every row, answer three questions:
- Who sees the failure, on your side and on the customer's side
- What the customer is told, and through which channel
- Where the request waits until a person clears it
A portal with a real exception queue behind it changes what your staff do all day. Without one, people go back to email and the portal becomes another place to check.
Step 6: write down who owns it after launch
Requirements cover the year after go-live too.
- Who answers when a customer cannot sign in
- Who applies security updates and platform upgrades
- Who changes a form when your process changes
- Where the code and hosting accounts live, and whose name is on them
- What happens if the people who built it become unavailable
Write the answer even when it is "we have not decided yet". An undecided line is useful to whoever quotes the work. A missing one turns into an argument after launch.
A readiness scorecard for client portal development
Score each line yes, no or unknown.
| Line | You are ready when |
|---|---|
| Roles | Every role is listed, with its access described in one sentence |
| Actions | Every action has a row, and each row says see or do |
| Source systems | Every field has one named system of record |
| Integration access | API access is confirmed for each system at your current plan |
| Permissions | Each action has a written rule covering both role and account |
| Security | Sign-in, session, isolation, audit and hosting answers are written down |
| Exceptions | Every action has a failure path with a named owner |
| Ownership | Maintenance, hosting and account ownership are settled in writing |
Unknowns are fine. Count them. If more than half the lines are unknown, your next step is a session with the people who do the work, since any quote you get today is a number produced without the facts.
Questions buyers ask about B2B customer portal development
What should be in a customer portal requirements document?
Roles, actions, source systems, permission rules, failure paths and ownership. That is the whole list. Screens, colours and feature names can wait.
How do we write requirements when our process is not documented?
Follow one real request through your business from start to finish, with the people who handle it. Write down what actually happens, including the parts that happen by email or over the phone. One traced request produces better requirements than a week of meetings about the future state.
Do we need every requirement before client portal development starts?
No. You need one workflow specified properly. Pick the request that costs your staff the most time, fill in its rows, and leave the rest at headline level. Building one workflow well teaches you more about the others than specifying everything at once.
Who should write the requirements, our team or the vendor?
Your team writes the roles, actions and rules, because those are facts about your business. A builder turns them into a technical scope and prices it. If a builder writes the actions without watching your process, read every line before you sign.
Using the worksheet with us, or without us
This sheet is worth filling in whether you build, buy or configure. We fill one in with you after a discovery call, and you keep the result whatever you decide.