What to Specify Before You Build an Internal Business Portal

The question that gets skipped

Ask five people inside a business what an internal portal needs to do, and it's common to get five different answers, each built around a different department's immediate pain point, describing five different systems rather than one. That gap isn't a communication problem to smooth over in a kickoff meeting — closing it is the actual planning work, and skipping it is one of the most common reasons internal portal projects run over budget, ship something half the business doesn't use, or get quietly abandoned partway through. Before anyone chooses a platform, a framework, or even a screen layout, six things need answers in writing.

1. User roles and permissions

This is the one worth spending the most time on, because it's also the one most often specified wrong from the start — not through carelessness, but because of how naturally people reach for the wrong model. The instinctive approach is to map roles onto job titles: Manager gets one permission set, Staff gets another, Finance gets a third. This works for the first version and breaks almost immediately after, because organisations aren't as clean as their org charts. A manager needs to approve leave for their own team but shouldn't see salary data for another department's team. A contractor needs read access to one project and nothing else, for a fixed period. A staff member gets temporarily asked to cover someone's leave and needs that access for exactly four weeks, not permanently.

A title-based model can't express any of that without either creating a new role for every exception — which turns into role sprawl within the first few months of real use — or quietly granting people more access than they need, which is worse and harder to notice. The fix is to design permissions around three things instead of one: the action being taken, the data it's being taken on, and the condition under which it's allowed (their own team's records, a specific project, a time-limited window). That's more work to specify up front. It's also the difference between a permission model that absorbs the first real-world exception and one that needs to be rebuilt to survive it.

2. The decisions the system must support

A portal isn't there to store data for its own sake — it exists so specific people can make specific decisions faster or more reliably than they could with what they had before. Before any screen gets designed, it's worth listing those decisions explicitly: who approves a purchase order over a certain value, who decides whether a customer complaint gets escalated, who signs off on a leave request. Each decision implies who needs to see what, in what order, and what happens if nobody acts on it in time. A data model built without this list tends to end up with every field anyone might conceivably want, and no clear path from "the data is there" to "someone acted on it" — which is a database with a login screen, not a working system.

3. Data model and its exceptions

The clean version of any business process — one customer, one order, one invoice — rarely survives contact with how the business actually operates. A customer who is also a supplier. An order with no linked customer because it came in as a walk-in. An invoice split across two cost centres. These aren't edge cases to handle later; they're usually a meaningful share of real records from day one, and deciding how the data model accounts for them is a business decision wearing a technical costume. Getting this wrong doesn't show up in the demo — it shows up months after launch, when someone hits the exception the model didn't have room for and either can't complete the workflow or forces the data into a shape that quietly corrupts the reporting built on top of it.

4. Integration points

Almost no internal portal exists in isolation. It needs to know who's logging in (an existing staff directory or single sign-on provider), it may need to read from or write to accounting software, and it may need to send email or WhatsApp notifications when something needs attention. Each integration point needs to be named specifically — which system, which data flows in which direction, how often — before development starts, because "it should probably talk to our accounting system eventually" is not a specification; it's a guess that becomes a much more expensive conversation once half the system is already built around the assumption that it wouldn't need to.

5. Audit requirements

What needs to be logged, for how long, and who is allowed to see the log, are design decisions, not something bolted on afterwards. A portal that handles personal data falls under Malaysia's Personal Data Protection Act 2010 (Act 709), which sets out accountability and security obligations for how personal data is processed — worth checking directly against the Act and current guidance from the Department of Personal Data Protection (pdp.gov.my) for what specifically applies to the data a given portal will hold, rather than assuming a generic answer covers it. Separately from any legal minimum, most businesses have their own reasons to want a record of who approved what: it's usually the only way to answer "who changed this and when" months later, and it's far cheaper to build in from the start than to retrofit onto a system that was never designed to keep one.

6. Acceptance criteria

"The system should be fast" and "the system should be easy to use" are not acceptance criteria — they're preferences with nothing to test against. "Search returns results in under two seconds for a table of ten thousand records" and "a new staff member can submit a leave request without training, on their first attempt" are. Acceptance criteria written in testable, specific terms, agreed before development starts, are what turn "is this done" from a matter of opinion into a checklist both sides can actually walk through together.

From answers to a working brief

Once these six areas have honest, specific answers in writing — particularly the role design, which is where most of the later rework tends to come from — they become the specification a fixed-scope build can actually be quoted against. JagaWeb's Fixed-Scope Project (from RM30,000, excluding SST) is scoped from exactly this kind of document. For a business that needs help producing its own honest answers first — mapping what's actually happening today before the same six questions get asked, less usefully, in a build meeting — the Essential System Review (RM1,500, reduced to RM999 until 16 September 2026, excluding SST) is built for that groundwork.