The integration nobody documented

Nordvik Bank's interface register listed nineteen integrations. We found twenty-three. The four extras had been running since 2011, two of them carried genuine customer impact, and one was a file that a finance analyst's machine collected over SFTP every Tuesday at 06:40 and pasted into a regulatory return.

None of this is unusual. It is the default condition of any platform older than its documentation process. The register records the integrations that went through governance; the estate contains the integrations that got built.

Look at behaviour, not at diagrams

Discovery has to be evidence-led, because the artefacts you would naturally trust are exactly the ones that omit the problem. We run five parallel sweeps, and each finds a class the others miss.

Note the recurring gap: everything time-boxed misses whatever did not run during the box. That is why the sweep has to cover a full business cycle. Quarter-end and year-end jobs are precisely the ones that are undocumented, high-impact, and invisible in a two-week discovery.

Start with who touches the data

The cheapest high-yield query is against the database itself. On Oracle, sampled session history tells you which programs, hosts and users actually touched the schema you are about to move.

-- Real consumers of the POLICY schema, by evidence rather than by register.
-- Caution: AWR retention defaults to 8 days. Snapshot this to a permanent
-- table nightly for a full quarter before you trust the absence of a caller.
select
    s.program,
    s.module,
    s.machine,
    s.user_id,
    count(*)                as samples,
    count(distinct trunc(s.sample_time)) as active_days,
    min(s.sample_time)      as first_seen,
    max(s.sample_time)      as last_seen
from   dba_hist_active_sess_history s
join   dba_objects o
       on o.object_id = s.current_obj#
where  o.owner = 'POLICY'
and    s.sample_time > sysdate - 90
group  by s.program, s.module, s.machine, s.user_id
order  by samples desc;

Two columns do the work. machine names hosts that no architecture diagram mentions, which is how we found a reporting box under someone's desk in a regional office. active_days separates a genuine daily integration from a one-off investigation, so you are not chasing a DBA who ran a count last March.

Classify before you panic

Not every undocumented interface deserves remediation. We sort them into four buckets, and the ratio at Nordvik was roughly 40 / 30 / 20 / 10.

• Retire. Nobody consumes the output. Prove it by switching it off in a controlled window and waiting a full business cycle. Silence is the evidence.
• Replace. Real dependency, poor mechanism. The Tuesday SFTP file became a read-only API with the same fields and the same schedule, because changing the consumer's habit was out of scope and did not need to be in it.
• Reproduce. Real dependency, acceptable mechanism, no owner willing to change. Recreate it exactly on the target, byte-identical output included, and log it as debt with a review date.
• Escalate. Real dependency, real risk, no owner at all. These need a name against them before cutover, and finding that name is a management task, not an engineering one.

The manoeuvre that catches the rest

Sweeps will not find everything, so the last step is deliberate: run the legacy system and the target side by side, then start darkening the legacy interfaces one at a time on a published schedule, keeping each one restorable within minutes.

Announce it. Broadly. The most reliable discovery instrument ever built is a colleague noticing their report is empty, and it is far better for that to happen on a Tuesday morning in a controlled window than at 03:00 on cutover night, when the person who knows why the file matters is asleep and the rollback decision belongs to someone who has never heard of it.

We budget eleven weeks for interface discovery and darkening on a platform of this age. It has never once been wasted time, and on two programmes it was the difference between a cutover and a rollback.