The eight questions an FSD never answers

An integration functional spec is rarely wrong. The problem is different: it is incomplete in a way you cannot see. Ten pages describe the objective, the systems, the frequency, the volumetrics and a field mapping table. All of it true. And still, between the approved document and the working iFlow there sit a dozen decisions someone will make alone, at the keyboard, without recording them.

Those decisions are the origin of most rework in an integration project. Not because they were made badly — they are usually reasonable — but because they were made by someone who did not have the information, and nobody knew they had been made at all.

The eight gaps

The list below is what shows up most often when you read an FSD looking for what is not there. Use it as a reading checklist before the first line of configuration.

1. What authentication mechanism does each side use?

The document says “consume the SuccessFactors OData API” and “send via SOAP to S/4HANA”. It does not say whether that is OAuth2 with SAML Bearer, Basic, a client certificate, or a managed token. Each answer changes the adapter, the security material to be created in the tenant, and who has to be involved on the customer side — usually a different person, with a deadline of their own.

2. What is the selection criterion at the source?

“Send employees every hour” does not say whether that means all of them, only those changed since the last run, or a specific subset. If it is a delta, it is missing what the delta is based on: a modification timestamp, a status, a control table. Without it you cannot build the OData query, nor guarantee the same message will not be reprocessed.

3. How is the volume handled?

“Up to 2,000 records per run” is volumetrics, not strategy. It is missing whether it all goes in one payload, whether the source paginates, whether the target accepts batches and of what size. A splitter added later changes the whole flow design; it is not a parameter tweak.

4. What is the exact contract at the target?

“Employee Replication SOAP service” is a functional label. What you need is the WSDL, the operation name and the endpoint — plus the expected response. Without the contract, the mapping is built against an imagined structure, and the first real run turns into a round of field-name corrections.

5. What does “field not used” mean in the mapping?

Mapping tables carry rows marked NA, - or “not used”. Ambiguous: should the field be dropped in the transformation, or sent empty to the target? Those are different behaviours, and targets usually treat absence and emptiness differently too.

6. What does the remarks column mean, technically?

“Format YYYY-MM-DD”, “concatenate with the surname”, “only when status = active”. These notes describe transformations nobody specified how to implement — and they get forgotten precisely because they look like formatting detail. Each one has to become an explicit rule in the XSLT or the mapping, with its source declared.

7. What happens when the retry policy is exhausted?

“Retry 3x at 5-minute intervals” describes half the behaviour. The other half is missing: after the third attempt, return an HTTP error to the caller? Persist to a Data Store for manual reprocessing? Send to a dead-letter queue? Notify? Without that answer, what gets delivered is a flow that gives up silently.

8. Who receives the alert — and from what severity?

“Notify by e-mail on error” does not say who, nor whether every failure becomes an e-mail. An integration moving 2,000 records an hour with an alert per message turns the team's inbox into noise within a week, and the alert loses its function exactly when it starts to matter.

Why the gaps get through

This is not carelessness on the author's part. An FSD is written by someone who knows the business process, and the eight questions above are technical architecture. The author correctly describes what the company needs; the missing decisions simply are not part of the document's vocabulary.

The failure point is the handover. The document is signed off as “complete” because it is complete on its own plane, and the next stage begins treating it as a technical specification, which it never was.

What to do about it

The intervention with the best return is cheap: separate what is written from what was inferred, in writing, before you start.

• Build the field list and, beside each one, the provenance of the information: the line of the document it came from. Anything with no provenance is not a requirement — it is your assumption.
• List the open questions explicitly, in the same place as the scope — not in an e-mail, not in a conversation. They have to survive a change of consultant.
• For each open item, decide what happens while there is no answer: an externalised parameter is almost always better than a hard-coded value, because it changes without a new deployment.
• Take the list back to the FSD's author. The goal is not to complain; it is to put the decision in the hands of whoever has the information.

None of these steps requires a tool. What a tool changes is the cost: doing this by hand for a workbook with dozens of sheets is laborious enough to be skipped under deadline pressure — which is exactly when skipping it costs most.

Where this touches what we build

iFlowMind's FSD import reads the document — Word, PDF, Markdown or spreadsheet, sheet by sheet — and returns the scope with two things beside each piece of information: the quotation of the passage it came from, and the list of what the document does not answer. On a real employee-replication FSD, that list has eight items — coincidentally, the same eight above.

What the tool deliberately does not do is fill the gap. A field with no provenance in the document does not show up filled in; an open question becomes an externalised parameter and stays visible on screen. It is the same discipline described here — only without depending on someone having the time to apply it.

Read next: Silent failure: when the iFlow doesn't error, it just stops.