Requirements for automating a business process: roles, data, integrations

Why a spec must detail roles, data and integrations

Estimates for automation usually diverge not because someone miscalculated, but because people assume different scope. Business describes a convenient process for staff. The implementer sees the high-level steps and doesn’t know how many exceptions, approvals and exchanges with other systems are hidden inside.

A good requirements document for automating a business process makes the scope verifiable. It should be clear where the work starts and ends, what’s included in the delivery, and what’s a risk or a separate task. Transparency isn’t for formality — it prevents debates later about “that’s what we meant”.

Most timeline extensions come from three under-described things in the spec: roles and permissions (who can do what), data (which objects and fields are required), and integrations (what exchanges happen and how failures are handled). Even a single overlooked participant — for example, accounting or security — can introduce new statuses, documents and checks.

Simple test: if the document reads like a wish list, it can’t be estimated. The spec must answer three questions: who performs each action and with what restrictions, what data is entered and changed, and which external systems participate and what happens if an exchange fails.

Example: “approval of a request” sounds short until you discover some requests go to the ERP, some to procurement, and only certain roles can see amounts. Without these details an estimate becomes guessing.

Define the goal and boundaries of the automation

Describe the automation goal in one clear paragraph: what exactly will become simpler, faster or safer, and for whom. A good goal reads as a measurable improvement, not “build the system”. For example: “Reduce approval time for equipment purchase requests for IT and accounting from 5 days to 2, eliminate manual email threads, and make status visible to all participants.”

Then fix the process boundaries: where it starts and where it ends. The start is usually an event (a need arises, a request is created), and the end is a result (order placed, invoice paid, equipment received). Specify which steps are definitely inside the automation and which remain “before” or “after”.

List out what is out of scope. This protects against hidden tasks like “integration will be added later”, “reference data afterwards”, or “one more report at the director’s request”. Better to list exclusions in simple phrases.

To make scope verifiable, add success criteria. For example: requests are created in the system via a single form (no Excel), status is visible to the requester and manager, notifications arrive on delays, decisions and comments history is preserved, and a report by deadlines is available for any month.

Roles and permissions: who participates and what they can do

Describe roles by function in the process, not by job title. The same person may be both requester and approver in one team, while in another those are different people. The clearer the roles, the more honest the estimate: permissions affect screens, checks, notifications and logs.

Usually 4–6 roles are enough. Don’t forget edge cases: an external participant (supplier, auditor, an employee of another legal entity with restricted access) and system roles.

Record permissions in a matrix: role vs. actions and objects. A basic set of actions is enough (view, create, edit, delete, approve, comment, attach files, export report), but explicitly state field-level restrictions. Which fields are read-only, which are hidden entirely (for example, budget, personal data, internal notes).

Also define “special permissions”: substitution during vacation, temporary access for incident investigation, access only to one’s own requests or to the department’s requests.

Don’t forget “no-human” scenarios: a system role (for example, “Integration Service”), scheduled jobs (close overdue requests), and automatic population of details or dispatching notifications. In automation projects these often account for a noticeable part of the scope.

Data: which objects and fields must exist in the system

Describe data in the spec as carefully as you describe process steps. The team needs to know exactly what is stored, what is entered manually, and what comes from other systems.

Start with main objects (entities): requests, contracts, counterparties, goods and services. For each object record where it appears in the process and who is responsible: who creates, checks, approves, or edits it.

Then list key fields with emphasis on required ones. The reason a field is required must be explained: needed for accounting, for reports, for limit checks or for integration. Also define format and constraints up front, otherwise these will surface during development and push timelines.

For each field, typically note briefly:

• whether it’s required and the rule when it becomes required
• data type, format and length (for example, IIN — 12 digits)
• allowed values or ranges (for example, amount > 0)
• source (user, reference data, integration) and who can change it
• what to do on empty or invalid values

Separately describe reference data and classifiers: who maintains them (for example, procurement), how often they are updated, and who approves changes. If a reference list comes from an external system, state which source is authoritative in case of discrepancies.

Don’t forget audit and change history: which fields are logged, who made a change, when, and retention period. Note personal and sensitive data locations and which roles have access. This affects permissions, storage and cost.

Scenarios and exceptions: how the process behaves in reality

Describe not only the “happy path” but daily occurrences: returns, pauses, errors, missing data. Otherwise the team will estimate a single scenario and ten more “suddenly” cases will appear later.

Start with the main scenario step by step: triggering event, who creates a request, which checks run, who approves, and what outcomes look like (approved, rejected, completed). Use simple verbs: “checks”, “signs”, “changes status”, “adds comment”.

Then add branches. For example, if a purchase request exceeds a limit, an additional approver is needed; if it’s below, only the department manager is required. Organizations that buy IT equipment (PCs, servers) often use such thresholds and rules, which strongly affect timelines.

List exceptions: what to do on rejection, missing data, integration error, duplicate request. Also record repeat actions: return for revision and re-approval, and rules like “previously approved isn’t re-reviewed” or the opposite.

To avoid drowning in details, set a minimal parameter set for each scenario: entry condition and outcome, responsible person and deadlines, required data, what happens on error, and who receives notifications (channel, timing, text).

For notifications, specify who needs them (requester, approvers, executor), when to send (immediately, one day before deadline), and what to do if someone is unavailable (substitute, escalation).

Integrations: what is exchanged and how failures are handled

Integrations often create the biggest variance in estimates. In the spec, list all external systems that need data exchange: accounting system, HR, CRM, electronic document workflow (EDO), email, SMS gateway, corporate user directory.

For each integration, describe not just “there’s an exchange” but verifiable specifics.

What to record for each integration

A consistent card for every exchange is useful:

• what we send and what we receive (with 2–3 example fields)
• format and protocol (JSON, XML, CSV, file, API)
• mode and frequency (online, batch, scheduled, manual by button)
• identifiers and mapping (which field is the key, what to do on duplicates)
• security requirements (who has access, how tokens/keys are stored)

Example: when creating a request, the system asks the directory for a person’s full name and department by employee number, and sends the request number, initiator and a file to EDO for signature. If EDO returns “rejected”, the request goes back for revision with a comment.

How to handle failures

Describe common errors in advance: external system unavailable, timeout, invalid format, identifier conflict. Specify whether there will be a message queue, how many retry attempts and with what intervals.

Also define who and how is notified: alert to the responsible person, log entry, a specific status or an “integration error” screen for manual handling and re-sending.

Non-functional requirements that affect the estimate

Non-functional requirements are often invisible on the process diagram, but they change the scope and schedule.

Start with load. Provide numbers: how many active users concurrently, how many requests or operations per day, which actions are most frequent (search, approval, document upload). These determine architecture, optimization and testing.

Then define availability. If the system must be 24/7 (for a bank or support service), redundancy, maintenance windows and degradation scenarios are required (what to do if some functions are unavailable). If nightly downtime once a week is acceptable, the solution is simpler and cheaper.

Also describe support: which events are logged, how quickly errors must be found, what metrics are monitored. Without this, it’s hard to estimate rollout and ongoing operation.

Minimum items to record:

• load: peak concurrent users and daily operations
• availability: acceptable downtime and maintenance windows
• logs and monitoring: what we record and retention periods
• security: authentication, roles, encryption in transit and at rest
• infrastructure constraints: where we host and which policies apply

Example: if policy forbids storing data outside the organization’s perimeter, additional deployment, backup and security checks are needed.

Interfaces, reports and documents: what we deliver to users

Describe not only the logic but what users will see: screens, reports and printable forms. These visible parts often take more time than expected.

Screens and forms

You don’t need final design, but simple prototypes and a field list are required. For each screen record its purpose (for which role and why), fields (required and read-only), actions (create, send for approval, return, close), validations (what is invalid and the error text), search and filters (which fields are used to find records).

Write validations in natural language. For example: “Delivery date cannot be earlier than today” rather than “Error 103”.

Reports, exports and print forms

A report isn’t just a table. Specify metrics, frequency, format and who can view it. If export is needed, say how it is triggered: manually by a button or scheduled automatically.

For print forms, record when they are required (for example, a service note or purchase request), who approves the template, which details are mandatory and what happens if the template changes after launch.

How to compile the spec: a 1–2 week plan

To prevent the spec becoming a set of vague wishes, build it in short cycles: clarify, record, test on real cases, then refine. This reveals gaps quickly and shows what most affects the scope.

A 1–2 week plan usually follows:

• agree process boundaries and participants: where a request starts and ends, who owns the outcome, which departments are involved
• describe the main scenario and frequent deviations: 5–10 real alternatives (return for revision, change of executor, urgent mode)
• fix roles and permissions: who creates, who approves, who sees financial fields, who can cancel or change status
• describe data with simple tables: entities (Request, Contract, Counterparty), required fields, reference data, example values and who fills them
• list integrations and failures: which systems participate, what we send, and what we do on error (retry, manual processing, notify)

Then agree on acceptance format. For example: “Request goes through 6 statuses, all decisions are logged, overdue approvals report generates within 1 minute, integration errors are visible to the responsible user.” If you work with an integrator (for example, GSE.kz), such criteria help align expectations and estimates before development.

How to make the estimate accurate and verifiable

An accurate estimate starts not with an hours number, but with clear units that can be recalculated. In a good spec requirements are broken down into blocks so you can see exactly what will be done for each block.

A practical approach: first define the block (interfaces, logic, data, integrations), then describe measurable elements. Instead of “build a request form”, state how many screens, which fields, what checks and which roles can edit.

Examples of verifiable units:

• screens and states: how many pages and variants (create, view, edit)
• fields and rules: requiredness, formats, calculations, auto-fill
• scenarios: main path plus 2–3 exceptions and errors
• exchanges: number of integrations and operations (send, receive, reconcile)
• reports and documents: count of templates and parameters

Also record risks and assumptions. A risk is an unknown (for example, an external service doesn’t provide test access). An assumption is something you treat as known (for example, the department list is already clean and up to date).

To keep the estimate verifiable after changes, agree a simple rule:

• any new requirement is a separate item
• each item gets measurable units and a reason
• re-estimation applies only to affected blocks
• spec version and change date are recorded at the end

Common spec mistakes and how to catch them early

The costliest mistake is confusing the goal with the means. You end up with a list of screens and buttons, but not an understanding of how people actually work and what should change. Simple check: can you run the process from start to finish using the spec without naming a specific system?

A second common problem is missing boundaries. The process quietly expands: neighboring departments, new approvals, extra documents appear. This almost always breaks the estimate. Fix start, finish and what you definitely won’t do in this iteration.

Roles are often listed but not turned into verifiable permissions. For example, “Manager” exists, but what can they do: create, edit, cancel, see others’ requests, start approval? If not specified, conflicting expectations surface at acceptance.

Data is often described too generally: “the request contains details and amount”. Later you learn you need currency, VAT, budget limit, attachments, link to contract, change history. Better to state the minimal field set and object relationships up front.

Quick checks before sign-off:

• there’s one paragraph “process goal” and a separate “how it works” section
• boundaries are shown: input, output, excluded areas
• each role has a matrix of actions and restrictions
• key objects list fields, requiredness and relationships
• integrations include formats, frequency, initiator and error handling

Short example: a purchase request missed the scenario “supplier changed the invoice”. At acceptance accounting needed to store the old version, the new version and the reason for change. Adding 2–3 real-life exceptions beforehand reduces such surprises.

Quick checklist before approving the spec

Before approval ask participants to read the document with one question: can everyone understand the task, estimate the scope and accept the result in the same way? If answers differ, fix it now rather than arguing during development.

Review takes 20–30 minutes if you treat the spec as a set of verifiable promises, not just a process description.

Minimum everyone must agree on

• goal in one paragraph, boundaries clear: what we do in the first version and what we definitely don’t do
• roles listed with permissions: who creates, who approves, who sees, who can cancel; highlight disputed points (for example, access to financial fields)
• data described as entities and fields: required fields, reference lists, formats (date, IIN, contract number), filling rules and owners
• main scenario and real exceptions step-by-step: what happens on return for revision, overdue, duplicate, input error, missing data
• integrations explicitly named: which data we send, how often, what counts as an error, who handles failures

Finally, ensure acceptance criteria are testable without interpretation: concrete conditions, sample input data and expected results. With that, estimates tend to be accurate and transparent.

Example: a spec for the request approval process, in plain language

Situation: a company with branches where employees create purchase requests. A request is approved by limits: up to 500,000 KZT the department manager is enough, above that financial control is required, and after approval procurement places the order with the supplier.

Roles described simply so it’s clear who does what: the initiator creates the request, attaches files, receives comments and sends it for approval; the manager approves or returns for revision; financial control checks budget and codes and can reject; procurement selects the supplier, records final price and closes the request; the administrator configures limits, reference data and access rights.

Data is easiest listed as objects with key fields. For example: “Request” (number, branch, amount, status, budget code, comment), “Items” (name, quantity, price), “Counterparty” (BIN, name), “Attachments” (type, file, who added).

Exceptions are short rules: if there’s no budget, the request moves to status “Rejected” with a reason; if a counterparty isn’t found, procurement creates a request to add it; if the manager returns the request, the initiator edits and resubmits.

Integrations can be described in one paragraph: the system queries budget balances from the accounting system, takes counterparties from a directory, and sends notifications by email. State what to do on exchange failures: retry, queue, notify the user.

Such a spec helps estimation: you can count screens (create, approval, list, card), rules (limits, statuses), exchanges (3 integrations) and reports (for example, “Requests by branch and status”).

Next steps: turn the spec into a work plan and launch

After the spec is fixed, the main risk is leaving “white spots” that surface during development. Collect all clarification questions and assign owners: who is responsible for roles, who for data, who for integrations, who for error handling rules. Also agree how you’ll store agreements so they are easy to verify.

Agree on artifact formats: roles and permissions table, list of entities and fields (with data sources), integrations matrix (what is sent where, how often, how success is confirmed) and an exceptions list with system reactions.

Run a joint walkthrough of the end-to-end scenario from start to finish. Business, IT and the contractor follow the steps and mark where screens are needed, which checks are mandatory, what to do on integration failures and which notifications are required.

A practical launch plan looks like: finalize questions and freeze the first spec version (with date and owners), split scope into phases with acceptance criteria for each, prepare a pilot (limited perimeter, real users, short timeline), collect feedback and expand the process by departments or functions.

If you need help designing and implementing, you can involve the system integration team GSE.kz. This is useful when you also need server and workstation selection for expected load and post-launch support.