Mapping application dependencies before a migration or an outage

Reference article · 7 min read

Most agencies can name their major systems. Far fewer can name everything those systems touch. A permitting platform is not just a web application and a database. It is also a nightly file drop to the county assessor, a service account that writes to a shared folder, a reporting extract that feeds the budget office spreadsheet, an address validation call to a state service, a printer queue for notices, and a desktop shortcut on a supervisor's machine that points at an old report server. When a migration, a patch, or an unplanned outage removes one of those pieces, the failure often shows up days later and somewhere else entirely.

A dependency map is the working inventory of those connections. It does not need to be elaborate. It needs to be current, specific enough to act on, and owned by someone. The payoff shows up twice: during triage, when you can rule things in and out quickly instead of guessing, and during a cutover, when you already know which interfaces have to be tested before the old environment is turned off.

What belongs on the map

Start with the categories that get missed, not the ones already in the architecture diagram.

• Interfaces and integrations. API calls, web services, database links, message queues, and point-to-point connections in both directions. Record which side initiates the connection, because that determines which firewall rule and which credential matters.
• Scheduled jobs. Anything on a cron table, Windows Task Scheduler, a job scheduler, or a database agent. Note what it runs, what it depends on, when it runs, and what happens if it does not run. Silent failure is the norm for these.
• Service accounts and credentials. Which account each process runs under, where the password lives, when it expires, and who can reset it. Accounts tied to a departed employee are a recurring cause of post-migration failure.
• File drops and transfers. SFTP, network shares, watched folders, and email-based transfers. Include the directory path, the naming convention, and who consumes the file downstream.
• Reporting and extracts. Scheduled reports, data warehouse loads, open data publishing, and the spreadsheets staff pull manually. The manual ones are real dependencies even though nothing automated touches them.
• Client-side pieces. Desktop shortcuts, mapped drives, saved ODBC connections, browser bookmarks pointing at internal URLs, thick clients, and printer or scanner configurations tied to a specific server name.
• Certificates and DNS names. Hostnames baked into configuration files on other systems are a common reason a cutover breaks something no one was watching.

Where to get the evidence

No single source is complete, so combine three kinds and reconcile them.

Machine evidence is the most reliable and the least interpretable. Network flow records show which hosts talk to which hosts on which ports over time. Firewall and proxy logs show allowed and denied traffic, including the rules written years ago for a purpose nobody remembers. Database audit or connection logs show which accounts connect and from where. Authentication logs show service account usage patterns. Run collection over a period long enough to capture monthly and quarterly cycles, not just a week, because year-end and quarterly processes are exactly the ones that fail after a move.

Configuration evidence comes from the systems themselves: scheduler tables, connection strings, integration configuration files, batch scripts, and the mapped drives in group policy. Searching configuration and script repositories for hostnames and IP addresses of the system being moved often surfaces dependencies the owning team did not know existed.

Human evidence fills the gaps machine data cannot explain. Flow data tells you that a workstation connects to a server every Tuesday. Only a person can tell you that this is how the payroll clerk produces the report the finance director expects on Wednesday.

Running short interviews that actually produce something

Keep them to twenty or thirty minutes and talk to the people who run the process, not only their managers. Ask concrete questions:

• Walk me through what you do on this system in a normal week, and what is different at month end and year end.
• What do you do when it is down? What breaks first, and what can wait a day?
• What files do you send or receive, and who is on the other end?
• Who do you call when something looks wrong?
• What do you have saved on your desktop that points at this system?

Write down names of people and organizations on the other end of every interface. During an outage, the map is only useful if it tells you who to call at the state agency or the neighboring county, not just that a connection exists.

Making the map useful during an outage

Structure the map so it answers triage questions in the order they get asked. For each system, record upstream dependencies (what it needs to work), downstream consumers (what breaks when it stops), the business impact of an outage at different durations, the owner of record, and the escalation contact on each external connection. A map organized only as a diagram looks impressive and answers none of those quickly.

Add a tolerance note to each dependency: how long the connection can be interrupted before someone must be told. A nightly file that can skip one night is a different planning problem from a real-time public safety interface. That single field is what turns the map into a maintenance window planning tool. You schedule work inside the gaps the map shows you, and you notify the parties whose tolerance you are about to exceed.

Keeping it current

Maps decay. Tie updates to events that already happen rather than to an annual review nobody schedules: change advisory board approvals, new interface requests, vendor onboarding, and account provisioning. Require that any change request touching an integration name the affected dependencies. Re-run flow collection periodically and compare it against the documented map, then investigate the differences. The differences are the point. Store the map where operations staff can reach it during an incident, including when the primary network or identity provider is the thing that is down.

What to require from vendors and integrators

Dependency discovery belongs in the contract, not in a hopeful assumption.

• Require the vendor to deliver a written interface inventory for the system they are replacing or hosting, including inbound and outbound connections, scheduled jobs, service accounts, and file transfer specifications.
• Require a cutover test plan that exercises every interface, including the ones that run monthly or quarterly, before the legacy environment is decommissioned.
• Require that the legacy environment stay available in a read-only or standby state through at least one full monthly and one full annual processing cycle where feasible, and define who pays for that period.
• Require notification obligations and named technical contacts for every interface the vendor owns, with a defined response commitment.
• Require that documentation be delivered in a format the agency can maintain itself, and that it is updated as a condition of milestone acceptance.

Ask directly how the vendor discovered dependencies rather than accepting a list. A list assembled from interviews alone will miss the automated traffic, and a list assembled from scans alone will miss the manual processes.

HQT works with state and local agencies on systems engineering and modernization planning, including dependency discovery and cutover readiness for legacy application environments.

Frequently asked questions