30. Migrating from Sparx / RSM / UML
Most readers of this book won’t have used Sparx EA, IBM Rational Software Modeler, ArchiMate, or other enterprise-architecture tools. If you haven’t, skip this chapter; it’s a translation guide, not a tutorial.
If you have used those tools — and especially if you’re trying to migrate an existing model — this chapter maps your vocabulary onto Archlang’s. The mappings aren’t always one-to-one. A few EA concepts have no Archlang equivalent because the language deliberately rejected them. A few Archlang concepts have no clean EA equivalent because the language explicitly added them.
Why the mappings aren’t clean
The traditional EA tools were built on a few premises Archlang doesn’t share:
- Diagrams are the primary artifact. Modelers draw boxes and arrows; the model is the picture. Archlang inverts this: the model is text, and diagrams are derived projections (Chapter 14).
- The ontology is large and fixed. ArchiMate alone has 50+ concept types (Business Actor, Business Service, Application Function, Technology Process, …). Archlang has four primitives (module, interface, process, view) plus user-defined kinds. The ontology is small and extensible.
- TO-BE vs AS-IS is explicit. Modelers carry flags or duplicate elements to distinguish current from proposed state. Archlang doesn’t — Git branches are the future state (Chapter 14 again).
- Stereotypes / archetypes / templates as a separate facility. Multiple parallel mechanisms for “this thing is a kind of.” Archlang collapses them into one: type form templates (Chapter 15).
What follows tells you how to express your existing concepts, what to drop, and what’s new.
Core element mapping
| EA concept | Archlang |
|---|---|
| Application component | service (or any custom subtype) |
| Application service | interface on a service |
| Business component | module (often system for higher-level grouping) |
| Business service | interface on a business component module |
| Business actor / role | actor (stdlib module kind) |
| Business process | process |
| Technology component | service, database; brokers/queues modeled as external_system (no built-in queue kind) |
| Technology service | interface |
| Data object / artifact | A field on the module that produces or owns it (not a separate primitive) |
| Capability | A facet on a module, or a custom facet kind |
| Stereotype | A type declaration (type service payment_service { ... }) |
| Archetype | Same as stereotype — a type declaration |
| Template | Same as stereotype — a type declaration |
The first observation: ArchiMate’s three columns (Business / Application / Technology) collapse into Archlang’s one tree. Layers in ArchiMate become labels in Archlang (labels.layer: business, labels.layer: application, …), and views slice by layer when needed.
Relationships
| EA relationship | Archlang |
|---|---|
| Composition (whole-part) | Nesting (service X { component Y { ... } }) or in clause |
| Aggregation | Less common; usually nesting works |
| Realization | The interface IS the realization. Don’t model it separately. |
| Assignment (actor to process) | Process step with the actor as caller |
| Used-by | Process step (caller > callee.interface) |
| Triggering | Process step, or subscribes: for async |
| Flow | Process step |
| Specialization | Subtype in the type system |
| Association | If it’s not one of the above, you probably don’t need it |
The biggest jump: most EA relationship types collapse into “a process step” or “containment.” The reason: process steps capture causality; containment captures ownership; the rest is detail.
Mindset shift. EA tools encourage drawing relationships first. You draw an arrow between two components and label it “Used-By” or “Triggers.” Archlang inverts this — you write process steps first, and the arrows are derived. If you find yourself wanting to add a relationship that isn’t a process step or containment, ask whether the underlying fact is causality (use a process), ownership (use containment), or classification (use a label or type). Almost everything reduces to those three.
What doesn’t transfer
Several EA concepts don’t have an Archlang equivalent. This isn’t oversight — they were deliberately excluded.
TO-BE / AS-IS markers. Archlang doesn’t have a status field on declarations. Branches in git play that role. Your “current state” model lives on main; your “proposed state” model lives on a feature branch. The structural diff (Chapter 14) shows the delta.
For migration: if your EA model has TO-BE artifacts, drop them. Use branches.
New / changed / existing flags. Same as above. The diff engine derives these from comparing two model snapshots.
Multiple parallel “views” of the same element. In Sparx, the same physical service can appear in five different diagrams, each with different connections drawn. In Archlang, the model is one; views are projections of that one model. You can have five views of a service; they’re all reading from the same canonical record.
Free-text “stereotypes” stuck onto elements. Sparx lets you tag any element with arbitrary stereotype strings. Archlang requires the stereotype to be a declared type. The benefit: type-level rules (required blanks, cascade behavior) attach to the stereotype. The cost: you can’t just slap a label and move on.
For migration: figure out what your stereotypes actually mean and write them as type declarations.
Constraint annotations as free text. Sparx lets you write OCL constraints in notes that humans read and tools ignore. Archlang requires constraints to be enforceable — required blanks (Chapter 17) and validation rules (Chapter 28). The model encodes only what the validator can check.
What’s new
Several Archlang ideas don’t have an EA equivalent. They earn their own learning curve.
Stable IDs. EA tools use names as identity. Archlang uses opaque IDs (Chapter 13) so renames don’t break references. There’s no equivalent in Sparx — renaming there silently breaks every diagram that referenced the old name.
The form-template type model. EA tools have stereotypes; Archlang has form templates that stamp content. The difference: stereotypes are tags. Form templates are requirements that propagate — a stereotype telling instances “you must fill in team” is enforced at parse time. Sparx’s nearest equivalent is a “tagged value with mandatory=true” but the propagation isn’t there.
Two compose-able propagation mechanisms. Template stamping (mechanism A) plus structural cascade (mechanism B) — together they let a single label or field set on a parent module reach every nested element. EA tools don’t have an equivalent; they require you to set the value on every element explicitly. See Chapter 18.
Git as the system of record. Sparx stores models in proprietary .eapx files (or Oracle/SQL Server back-ends). Archlang stores .arch files in your repo, next to the code they describe. The model is reviewable in pull requests, branchable, mergeable. There’s no migration import/export to do — once it’s in .arch files, git is the tool.
A migration approach
For an existing Sparx model with ~500 elements:
Phase 0 — Decide what to keep. Most Sparx models accumulate cruft over years. Identify the core 50-100 elements that represent the actual current architecture. Set aside the rest.
Phase 1 — Define your kinds first. Look at the stereotypes in use. Decide which ones map to existing stdlib kinds (service, database, external_system, actor, frontend) and which need custom types (Chapter 29). Write kinds.arch first.
Phase 2 — Migrate modules in dependency order. Start with the leaves — services that don’t call anything. Declare them in .arch files with their kind, name, team, and key labels. Add interfaces. Don’t draw processes yet.
Phase 3 — Add processes. Walk through Sparx’s sequence diagrams and activity diagrams. Each becomes a process in Archlang. The arrows in your diagrams become process steps.
Phase 4 — Add views. Recreate the saved Sparx views as view declarations, using focus, group by, and layout.
Phase 5 — Add validation. Identify the rules you wished Sparx had enforced — required runbook URLs, required compliance labels, required teams. Encode them as required blanks on your kinds.
By the end you’ll have ~half the source you had in Sparx (Archlang is more compact), zero broken diagrams, and the ability to review architecture in pull requests for the first time.
What to set realistic expectations about
- Initial diagrams will look different. Archlang’s layouts (ELK, Dagre) are auto-generated; you can’t pixel-place nodes. The first time you generate a diagram from a migrated model, it’ll look unfamiliar. Within a week most people prefer the auto-layout because it’s consistent.
- You’ll lose some Sparx features. Calendar-based forecasting, gap analysis tools, ArchiMate-specific viewpoint frameworks — those don’t exist in Archlang. If they’re load-bearing in your organization, evaluate whether they’re worth keeping in parallel (Sparx for those reports, Archlang for the architecture).
- Custom Sparx scripts won’t port. They were written against the Sparx COM API. The equivalent in Archlang is
@archlang/core(Chapter 24) — easier to write, but the rewrite cost is real. - The vocabulary takes weeks to settle. Teams used to “Application Service” + “Business Process” + “Information Object” will write things in Archlang’s vocabulary awkwardly at first. The book chapters speed the transition; resist the urge to recreate the EA vocabulary literally as user-defined kinds.
Summary
- Most EA concepts map to module / interface / process / view, with stereotypes becoming types.
- ArchiMate layers become labels; views slice by layer.
- TO-BE / AS-IS markers are replaced by git branches.
- Stable IDs solve the rename-breaks-everything problem Sparx never solved.
- Form templates plus structural cascade replace stereotypes-with-tagged-values plus manual per-element configuration.
- The migration approach: kinds first, then modules leaf-first, then processes, then views, then validation.
End of Part VI
That’s the book — twenty-nine chapters from the foreword’s three commitments through six worked designs. The appendices (Grammar, Keywords, Stdlib Kinds, Cheatsheet) are dense lookup once you know what you’re looking for.
If you read every chapter in order, you now have the language, the metamodel, the tooling, and a sense of how real systems get modeled. The next step is your own .arch file — and the loop the editor extensions give you, where you save and the diagram updates. That loop is where the language earns its keep.