Migrating from Archi: What Round-Trips and What Doesn't

Nobody migrates away from Archi because it can't model something. Archi is free, open-source, ArchiMate-native, and has been the default entry point into ArchiMate for over a decade. If you're looking at Mooodels as an Archi user, the question you actually have isn't "can this tool do what Archi does" — it's narrower and more useful than that: if I import my model, work in it, and export it back, what comes back exactly as it left, and what doesn't? That's a fair question to ask of any migration path, and it deserves a specific answer rather than a reassuring one.

This article gives you that answer. It covers what maps cleanly, what's a known lossy boundary and why, how identity is matched so a second import updates your model instead of duplicating it, and a verification method you can run yourself on a real model before you trust the pipeline with anything that matters.

Why this is a narrower question than it looks

Most tool-migration writing spends its first half convincing you the destination tool is capable — that it has elements, relationships, views, the right metamodel. That conversation doesn't apply here. Archi already has all of that, correctly implemented against the ArchiMate specification, for free. Nobody using Archi is migrating because Archi is missing capability. They're migrating because they want something Archi doesn't offer as a browser-based, model-native tool: a canonical model that AI can propose changes against as reviewable patches, deterministic rule checking across the whole model rather than per-diagram inspection, or Git-friendly serialization instead of a single opaque XML blob.

Which means the actual migration risk isn't conceptual, it's mechanical: does the specific model you've built over the last three years — with its specific folder structure, its specific diagram layouts, its specific documentation fields — survive an import into a different canonical model and an export back out, or does something quietly go missing along the way. That's the only question worth answering carefully, and it's the one this article answers.

What maps cleanly

The core of an ArchiMate model — the part that actually carries architectural meaning — maps onto the destination canonical model with very little friction, because both tools are describing the same kind of object graph underneath very different editing surfaces.

• Elements. Every ArchiMate element type, across all layers — business, application, technology, motivation, strategy, implementation — has a direct counterpart under the ArchiMate profile on the other side. Type, name, and identity all carry over.
• Relationships. Serving, realization, assignment, triggering, flow, composition, aggregation, specialization, access — the full relationship set imports with its type, direction, and endpoints intact.
• Folders. Archi's folder tree is preserved as the organizing structure after import. If an element lived in Application/Integration/Legacy, it lives there after import too.
• Views, with layout. Diagram geometry — position, size, which elements and relationships appear on which view — comes across. A view you built by hand doesn't come back as an auto-laid-out mess; it comes back where you put it.
• Documentation. The free-text documentation field on elements, relationships, and views round-trips as plain text attached to the same object.
• Properties and tagged values. Archi's custom properties — the key/value pairs teams use for ownership, lifecycle state, cost center, whatever a given governance process needs — map onto the destination model's properties and travel with the element.

In practice, this covers the overwhelming majority of what a real ArchiMate model contains. If your model is elements, relationships, views, documentation, and properties — which describes most production ArchiMate repositories — the import is close to lossless before you even get to the parts that need special handling.

How the exchange actually works

Mooodels doesn't read Archi's native .archimate XML directly, and it doesn't ask you to hand-convert anything. The exchange runs through a dedicated interchange step that both sides know how to produce and consume. On the Archi side, a jArchi script walks the live model and writes an export; a second jArchi script reads an export back in and reconstructs elements, relationships, folders, and views inside Archi. On the receiving side, the same exchange is read straight into the canonical model, and written straight back out of it.

The detail worth knowing here: this is the same exchange path used for Sparx Enterprise Architect. It isn't an Archi-specific mechanism with a Sparx-specific one bolted on beside it — one exchange, driven by a matching pair of scripts on each tool. That matters practically, not just architecturally. A fidelity fix made for one integration benefits the other automatically, and a model that started life in Archi and later needs to be handed to a Sparx-based team (or the reverse) doesn't need a second translation layer invented for the occasion.

What crosses is defined by data, not by presentation. Concretely, the exchange carries the identity of each object, its type, its name, its documentation, its properties, its position in the folder hierarchy, the endpoints and direction of every relationship, and the geometry of every view — which shapes are on it, where they sit, how large they are, and which connectors are drawn between them. Everything on that list is something a person could point at and say what it means for the architecture. Nothing on that list is a rendering preference. That distinction is the design principle the whole exchange is built around, and it's also what predicts, quite reliably, which of the rarer cases below survive and which don't.

The round-trip envelope: how identity survives a trip through a different model

The canonical model doesn't have a native concept of, say, an Archi-specific specialization label, or the exact size of a shape on one particular diagram. Rather than dropping that information because it doesn't fit the schema, the exchange carries it in what amounts to a round-trip envelope attached to the relevant object: source identity, folder path, diagram geometry, specializations, and documentation all travel inside that envelope even when the canonical model has nothing structural to do with them internally. On export back to Archi, the envelope contents get written back into native Archi constructs, so nothing that arrived gets silently thrown away just because the canonical model doesn't have a first-class slot for it.

The same mechanism covers root-level tagged values — the properties attached to the model itself rather than to any one element, which teams often use to record a version stamp, an owning department, or the reference architecture edition a repository is aligned to. Those aren't attached to anything the canonical model reasons about, so they'd be the easiest thing in the world to lose in translation. They ride in the envelope and come back out where they started.

This is also what keeps identity stable across a round trip. An element that came from Archi keeps a reference back to its Archi source ID, so a rename on that side is recognized as a rename of the same object on export, not as "delete one element, create an unrelated one with a similar name." That distinction is what makes iterative work — import, edit over several sessions, export, re-import later — safe rather than a one-way trapdoor.

Specializations and custom element types

Many mature Archi models don't stop at the stock ArchiMate element types. Teams routinely define specializations — "Legacy Application" as a specialization of Application Component, "Third-Party API" as a specialization of Application Interface — to carry organization-specific distinctions the base metamodel doesn't express on its own. These specializations aren't part of the ArchiMate specification itself, which means a generic canonical model has no built-in slot for them either. They travel inside the round-trip envelope alongside geometry and documentation: on import, the specialization label attaches to the element as envelope metadata; on export, it's written back as a proper Archi specialization rather than flattened into a generic comment or a property field no governance process expects to find it in. If your model leans on specializations to encode a local taxonomy, that taxonomy survives the trip — it just isn't something the canonical model treats as a first-class type distinction the way it treats the base ArchiMate types.

What happens on the second import

The first import is the easy case: the destination model is empty, everything arriving is new, and nothing can collide. The interesting case is the second one, three weeks later, after your colleague has added forty elements on the Archi side and you've been working on views in the browser. That's the case that decides whether the pipeline is a one-time conversion or a mechanism you can live with.

Matching happens on identity first. Every object that arrived from Archi carries its source ID, and on re-import that ID is what decides whether an incoming object is the same object you already have. If the ID matches something in the model, the existing object is updated in place — name, documentation, properties, folder, geometry all refreshed — rather than a near-duplicate being created next to it. If the ID matches nothing, the object is genuinely new and gets created.

Where identity is absent — typically for objects created on the other side that have never been through a round trip, or for content assembled by hand — matching falls back to name plus type. An Application Component named "Payment Gateway" coming in against an Application Component named "Payment Gateway" already in the model is treated as the same thing, not as a second one. That fallback is deliberately conservative: it requires both the name and the type to agree, so an Application Service and an Application Component with the same name stay distinct, which is exactly what you want in a model where the same word legitimately names several things at different layers.

The practical consequence is that re-import is an update operation rather than an append operation. You can run it repeatedly, on a schedule or on demand, and the model converges rather than growing a duplicate tail. It also means the one thing worth being disciplined about is renaming: if an object has no source identity and someone renames it on the far side between syncs, the fallback has nothing left to match on and will treat it as new. Objects that have been through a round trip at least once are immune to that, because from then on the identity, not the label, is what's being compared.

What doesn't round-trip, and why that's a decision

Here's the part most migration guides gloss over, and the part that actually matters if you're deciding whether to trust this for production work. A handful of things in an Archi model don't survive the round trip unchanged, and all of them are documented, deliberate scoping decisions rather than gaps someone forgot to close.

Walking through each lossy item in turn:

Embedded images

Archi lets you drop a raster image directly onto a view — a logo, a screenshot, a network diagram photographed off a whiteboard. That image isn't an ArchiMate element; it's page furniture. The canonical model stores architecturally meaningful objects, not arbitrary binary assets pasted onto a canvas, so an embedded image doesn't get imported as anything and doesn't reappear on export. If you rely on embedded images to annotate views, that annotation needs to live somewhere other than inside the model — a linked document, a caption in the view's own documentation field, or an image reference maintained outside the model rather than pasted into it.

Reserved visual style tokens

Archi's XML has a set of internal rendering flags used by Archi itself for specific display behaviors that don't correspond to anything in the ArchiMate specification — they're Archi implementation details, not modelling semantics. A handful of these reserved tokens don't have a meaningful equivalent to preserve, because they were never describing the architecture in the first place; they were describing how Archi's own renderer behaves in an edge case. These are excluded on purpose rather than approximated badly.

Element nesting flattened to folder membership

Archi views support visually nesting one element inside another — a component drawn inside the boundary of the container it belongs to, purely as a view-level containment relationship rather than a folder or a formal composition relationship. The canonical model represents organizational structure through folders and through explicit composition/aggregation relationships, both of which are semantically stronger and more queryable than "this shape happens to be drawn inside that shape on one particular view." On import, that visual nesting is flattened: the nested element keeps whatever folder and relationship structure it actually has, but the pure visual containment on that one view doesn't carry over as its own construct. If the nesting was standing in for a real composition relationship, model that relationship explicitly and it will round-trip like any other relationship — the loss is specifically the freeform visual nesting that had no semantic backing.

Connector routing and dash styles following the type default

Archi allows fine manual control over how an individual connector is drawn — custom bend points, a hand-picked dash pattern independent of what the relationship type would normally imply. Connectors render based on the relationship type's default routing and line style, consistently, across the whole model. A serving relationship looks like a serving relationship everywhere; a flow relationship looks like a flow relationship everywhere. What's lost is the ability for one specific connector, on one specific view, to be manually styled differently from every other connector of the same type. What's preserved is the far more valuable property that a diagram someone unfamiliar with the model is reading can trust the notation consistently, without checking whether this particular connector was styled differently by hand.

Why this is scoping, not an oversight

It would be easy to read that list as "things that just haven't been built yet." That's not what it is. Each item on the lossy side shares a property: it's presentation-layer flexibility that exists in Archi specifically because Archi is a general-purpose diagramming surface with an ArchiMate metamodel underneath it, not because it carries architectural meaning that a model-native tool is obligated to represent.

A model-native tool has to draw a line somewhere between "this is the architecture" and "this is how one person decided to draw the architecture on one Tuesday." Free-form per-connector styling and pasted-in images sit firmly on the drawing side of that line.

The alternative — trying to preserve every pixel-level styling choice Archi permits — would mean the canonical model has to carry per-object rendering overrides for things that have no bearing on what the architecture actually says. That's exactly the kind of accumulated, ungoverned visual state that makes diagrams drift from the truth over time in diagram-first tools generally: two connectors of the same relationship type looking different for reasons nobody remembers three years later. Scoping the lossy boundary to presentation-only, semantically-empty details is what keeps the rest of the round trip — the part that actually is the architecture — reliable.

A realistic verification approach

None of the explanation above should be taken on faith, and it isn't meant to be. Before you trust this pipeline with a model anyone depends on, run the verification yourself — it takes under an hour on a real model and gives you a concrete answer specific to your own content, rather than a general one about the mechanism.

1. Start from a real model, not a toy one. Use an actual Archi repository you maintain — ideally one with views you've hand-tuned, folders you actually use, and properties your governance process depends on. A model built purely to demonstrate the happy path won't tell you anything about your edge cases.
2. Import the model. Confirm element counts, relationship counts, and view counts match what you started with. A mismatch here is the first thing to chase down before going further.
3. Spot-check the views that matter most. Open the two or three diagrams you'd be most upset to see degraded — usually the ones used in governance reviews or shared outside the architecture team — and confirm layout, labels, and documentation look right, not just present.
4. Export back to Archi. Run the export and open the resulting .archimate file in Archi itself, not just in the tool you imported into. The round trip isn't verified until the file lands back in the tool it came from and Archi accepts it as valid.
5. Diff the two Archi files. Compare the original export against the round-tripped one — a plain text diff on the XML will surface changes, though a semantic diff at the element/relationship/property level is more useful for judging whether a change is meaningful or cosmetic. Expect differences in the areas covered above: embedded images gone, some reserved style attributes absent, manually nested elements now flattened to folder membership, hand-styled connectors now following their type default.
6. Re-import the round-tripped model and confirm it updates rather than duplicates. This is the step most people skip, and it's the one that tells you whether identity matching is doing its job on your content. Counts should be unchanged after the second import, not doubled.
7. Confirm nothing meaningful was lost. "Meaningful" here means: does every element still exist, does every relationship still connect the same two things, does every property value match, does every view still contain the elements it should. If the diff only shows the documented lossy boundary and nothing else, the pipeline has done its job. If it shows anything outside that list — a dropped property, a relationship that changed type, a documentation field that got truncated — that's a real finding worth investigating before you commit to the migration, not something to explain away.

This same procedure works both directions, and it's worth running the reverse too if your workflow involves handing a model back to an Archi-only colleague: export from the other tool, open in Archi, make a small real edit, re-import, and confirm the edit landed on the right element rather than creating a duplicate. A migration path that only round-trips cleanly in one direction is a much weaker guarantee than one that holds up both ways.

A useful check to run by hand, once, is a raw count comparison rather than a full XML diff — it's fast, and it tells you immediately whether to expect the detailed diff to be clean:

Original .archimate export:
  elements: 214   relationships: 187   views: 19   properties: 96

Round-tripped .archimate export (after import + export):
  elements: 214   relationships: 187   views: 19   properties: 96
  images removed: 2 (both were logos pasted onto the cover view)
  connectors re-styled to type default: 5 (previously hand-dashed)

If the element, relationship, view, and property counts match exactly and the only reported differences fall inside the documented lossy boundary, you have a clean result. If any of those four counts differ, stop and investigate before doing anything else — a mismatched count means something outside the documented boundary happened, which is the actual failure mode worth catching.

Putting the model under version control

One of the more common reasons Archi users start looking around in the first place is history. A .archimate file is a single XML document, and while it is technically diffable, a change to one element's documentation can produce a diff that touches a large, unrelated span of the file depending on how the tool happened to serialize it that day. That makes review harder than it should be: you can see that the model changed, but not cleanly what changed.

The canonical model is serialized deterministically — the same model always produces byte-identical output, with stable ordering and stable identifiers, so a diff between two versions reflects exactly the edits somebody made and nothing else. Adding one relationship shows up as one relationship added. Rewriting a documentation field shows up as that field, in that element, changed. This is what makes a model reviewable in a pull request the same way code is: someone who wasn't in the modelling session can read the diff and understand the change without opening a tool.

For a migrating team, the practical advice is to commit the very first import before anyone edits anything. That commit becomes your ground truth. Every subsequent change — whether made on the canvas, proposed by AI as a patch, or arriving from a re-import off the Archi side — lands as a diff against a known-good baseline, which means "what actually changed since we migrated" is a question with a precise answer rather than a reconstruction exercise.

Working across both tools during a phased migration

Few teams flip a switch and move an entire architecture practice from one tool to another in a single afternoon. More often, migration is phased: one team pilots the new tool while others keep working in Archi, or a single architect uses it for new work while reviewing legacy diagrams that still live in Archi. That pattern only works if the round trip is reliable enough to run repeatedly, not just once as a one-time conversion.

This is where the shared exchange matters beyond the single-import case described above. Because identity is preserved through the round-trip envelope, a model can move back and forth between the two tools across many cycles — import, edit, export, hand off, re-import — without accumulating duplicate elements or orphaned copies each time. The practical implication for a phased rollout: you don't have to pick a single migration weekend and freeze the model on both sides while it happens. A hybrid period, where some views are actively maintained in Archi and others in the new tool against the same underlying model, is something the exchange is built to tolerate, provided both sides stay disciplined about moving models through the actual import and export steps rather than editing an exported file by hand in between.

What that discipline does require is a shared answer to a boring question: for any given piece of work, which tool is authoritative right now. The mechanism will faithfully carry whatever it's given in either direction, which is precisely why two people editing the same element in two different tools between syncs is a process problem the tooling can't solve for you. Agree on it before the parallel period starts, not after the first conflict.

The same reasoning applies if part of your organization is on Sparx EA rather than Archi. Because both integrations use the identical exchange, a model can, in principle, move between all three tools using the same round-trip discipline described here — the verification approach doesn't change, only which tool is on the other end of the export.

What this means in practice

If your Archi model is mostly elements, relationships, views, documentation, and properties — which is true of most production ArchiMate repositories, because that's what ArchiMate governance processes actually consume — the import into Mooodels will feel close to lossless, because it largely is. The exceptions are narrow, specific, and consistent: pasted-in images, a small set of Archi-internal rendering flags, freeform visual nesting with no semantic backing, and manually overridden connector styling. None of those carry architectural meaning on their own; all of them are things you can verify are absent, rather than things that go missing without warning.

The honest way to evaluate a migration path isn't to ask whether it claims to be lossless — every tool claims that. It's to run the import, run the export, and read the diff yourself. That's what the round-trip envelope and stable source identity are built to make possible, and it's the same test worth applying to any tool claiming interoperability with the model you already trust.