Asset Relationships
Workflow for mapping dependencies between assets — linking applications to devices, databases to servers, applications to databases. Critical for migration sequencing: if App A depends on Database B, both must be in the same move group (or Database B must migrate first). Unmapped dependencies are one of the most common causes of migration failures.
Overview
Asset relationships represent the real-world connections between your systems. They are the difference between a migration plan and a guess. Without relationship mapping, you risk migrating an application before its database is available on the target environment, or cutting over a web server before its backend API is in place — either scenario results in an outage that could have been prevented.
Clarity Migrate supports four relationship types: runs-on (Application hosted on a Device), uses (Application consumes a Database), depends-on (Device communicates with another Device), and integrates-with (Application sends or receives data from another Application). Each relationship also carries a Criticality level — Critical, High, Medium, or Low — which drives sequencing urgency. A Critical dependency means the dependent asset will break if the target isn't migrated first.
Relationship data feeds directly into the move group and wave planning features. When you assign an application to a wave, Clarity will warn you if that application has a Critical or High dependency on an asset assigned to a later wave. The dependency graph visualisation in Analytics → Graph gives you a bird's-eye view of your entire relationship network, making it easy to spot clusters that must co-migrate, long dependency chains that constrain sequencing, and isolated assets with no mapped relationships that might be missing from the picture.
When to Map Relationships
- After initial CMDB population, before migration wave planning. Relationship mapping is a pre-requisite for accurate wave planning. Do it before assigning assets to waves, not after.
- When assigning assets to move groups. Always check relationships before locking in a move group assignment. An asset with a Critical dependency must be in the same move group as — or an earlier wave than — the asset it depends on.
- When an unexpected dependency is discovered. Dependency discovery is an ongoing process. Update relationships whenever a new connection is found — during technical interviews, application owner reviews, or network diagram analysis.
- Before executing any migration wave. Run a final dependency check against every asset in the wave immediately before execution. Last-minute scope changes can introduce new violations.
- During post-migration troubleshooting. If an asset fails after migration, check the relationship map for missed dependencies — an unresolved connection to an unmigrated or unreachable system is often the root cause.
Features
Step-by-Step Workflow
Before mapping, ensure you're using the correct relationship type for each connection:
- runs-on — an Application is hosted on a Device (server, VM, or host). Use this to link every application to the infrastructure it runs on.
- uses — an Application reads from or writes to a Database. Use this for all application-to-database connections.
- depends-on — a Device communicates with another Device at the network or infrastructure level (e.g. a load balancer that depends on backend servers).
- integrates-with — an Application sends or receives data from another Application via API, message queue, file transfer, or any other integration mechanism.
Choosing the right type ensures the dependency graph renders correctly and that wave planning warnings are triggered at the right level.
You do not need to map every relationship before starting wave planning — but you do need the Critical and High ones. These drive sequencing decisions. A Critical dependency means: if the target asset (the thing being depended upon) is not migrated first, the dependent asset will break during or immediately after migration. Focus your initial mapping effort on Critical and High relationships, then fill in Medium and Low over time.
Navigate to CMDB → Applications. Start with applications rather than devices — applications typically have the highest number of dependencies (they run on devices, use databases, and integrate with other applications). Working top-down from applications ensures you capture the most sequencing-critical relationships first.
Open each application record and navigate to the Relationships tab. Click Add Relationship, select type runs-on, search for the host device by name or IP address, set the criticality level, and click Save. Most applications run on 1–2 devices; clustered or load-balanced applications may run on 3–5. If an application runs on a device you haven't imported yet, add the device to the CMDB first.
Still on the application's Relationships tab, add uses relationships to each database the application reads from or writes to. Set criticality to Critical for production databases — the application cannot function if the database is unavailable. Set Medium or Low for read-only reporting databases or archives where a short outage is tolerable.
For applications that call other applications via REST API, SOAP, message queue, SFTP, or any other integration channel, add integrates-with relationships. These are often the hardest to discover — check application architecture diagrams, API gateway configurations, and interview application owners. Undiscovered integrates-with relationships are a common source of post-migration integration failures.
Navigate to Analytics → Graph and review the full dependency map. Look for:
- Isolated assets — nodes with no relationships. These may be missing mappings or genuinely standalone (verify which).
- Clusters — tightly coupled groups of assets where everything depends on everything else. These should typically co-migrate in the same move group.
- Long dependency chains — e.g. A → B → C → D. The chain constrains sequencing: D must migrate first, A must migrate last. Identify these early so wave planning can accommodate them.
- Circular dependencies — A depends on B which depends on A. These require a special migration strategy (parallel cutover or temporary bridging). Flag them immediately.
For each dependency chain, verify that the depended-upon asset is in an earlier wave than the dependent asset. The general rule: the asset at the bottom of the chain (the one others depend on) must migrate first. For example: a Database must be in Wave 1, and an Application that uses it can be in Wave 2. If both must migrate together, assign them to the same move group within the same wave.
Clarity will display a warning badge on any move group or wave assignment that violates a Critical or High dependency — use these warnings as your checklist.
After adjusting move group and wave assignments, return to Analytics → Graph and re-check for dependency violations. Clarity also provides a Dependency Validation report (Analytics → Reports → Dependency Violations) that lists every relationship where the dependency order is not respected. This report should show zero violations before any wave is approved for execution.
Real-World Example
During Wave 2 planning, the team maps relationships for the 15 applications in scope. The process takes two days — a mix of reviewing architecture diagrams and interviewing application owners. Several critical findings emerge immediately.
Finding 1: Application HR Portal has a runs-on relationship with 2 devices already assigned to Wave 2 — correct. But it also has a uses relationship with database HR_DB, which is currently assigned to Wave 3. This is a dependency violation: HR Portal cannot function without HR_DB. The team moves HR_DB to Wave 2 and places it in the same move group as HR Portal to ensure they cut over together.
Finding 2: During the integrates-with mapping step, the team discovers that HR Portal calls the SSO Service application for all user authentication. SSO Service was previously marked Out of Scope — it was assumed to be staying on-premises. But if HR Portal migrates to the cloud and SSO Service stays on-premises, latency will make authentication unusably slow. The team re-scopes SSO Service as In Scope, assigns it to Wave 1 (it must migrate before HR Portal), and updates the dependency relationship criticality to Critical. Two hidden dependencies discovered, both resolved before a single server moves.
Tips
You don't need a complete dependency map before you can start wave planning — you need the Critical and High ones. Map those first, plan waves, then fill in Medium and Low as time allows. Don't let perfect be the enemy of good: a partial map is far better than no map.
Circular dependencies (A depends on B which depends on A) cannot be resolved by sequencing alone — they require a special migration strategy such as parallel cutover or a temporary compatibility bridge. The graph view makes these immediately visible. Identify them early so the migration architect can design a strategy before execution day.
When a relationship forces a specific execution order, document it in the move group description (e.g. "Must migrate before Wave 2 HR Portal move group — HR_DB dependency"). This ensures the execution team understands the constraint even if they haven't reviewed the full relationship map.
If your legacy CMDB, network diagram tool, or application portfolio management system already has relationship data, export it and use the Bulk Relationship Import feature rather than mapping each relationship manually. A well-structured export can save days of manual data entry.
Common Mistakes
Wave planning without dependency data is guesswork. Move group assignments made before relationships are mapped almost always need to be revised — often at the last minute, when changes are disruptive. Map Critical and High relationships first, then assign move groups.
An unmapped Critical dependency discovered during execution — when servers are already being moved — requires emergency schedule changes, rollbacks, or accepting an extended outage window. The cost of discovery during execution is 10× the cost of discovery during planning. Interview application owners early and specifically ask about API integrations and shared databases.
Over-mapping Low-criticality relationships creates noise in the dependency graph and makes it harder to see what actually matters for sequencing. Reserve Low criticality for connections where a short outage is genuinely acceptable and has no sequencing implications. If you're unsure, use Medium. Keep Critical and High for connections that would cause an immediate, visible failure if not respected.
Individual relationship records are easy to add but hard to reason about in isolation. The graph view reveals the emergent structure — clusters, chains, and circular loops that are invisible when looking at a list. Run a graph review after every major relationship mapping session and before every wave approval.