How to migrate a model to a different metamodel

Sometimes a model needs to move to a different metamodel — a new version of a standard, a corrected metamodel replacing a flawed one, or a switch to a different notation entirely.

Farkitect can remap an M1 model from one M2 to another, matching element types and properties by name, and it shows you exactly what will and won’t survive before anything is written.

You need contributor access or above.

Moving to a new version of the same metamodel? If the new version has the same name as the one in your project, upgrade the metamodel instead. An upgrade keeps every element’s id and its diagrams, and lets you decide what happens to removed types. Migrate is for switching a model to a different metamodel that sits beside the old one.

Run a migration

1. In the Explorer, select the M1 package whose metamodel you want to change
2. Open the Properties panel and find the Imports section
3. Hover the import you want to replace and click the ⟳ (circular arrows) icon — “Migrate to different version”
4. In Target Metamodel, choose the metamodel to move to
5. Click Preview Migration
6. Read the report (see below)
7. Click Apply Migration

Nothing is written until step 7. Preview is read-only, so you can run it as often as you like.

Matching is by name

This is the thing to understand before you start.

Farkitect maps the old metamodel to the new one by name, not by identity:

• An element type called Application Component in the old M2 maps to an element type called Application Component in the new one
• A property maps by its owner and name together — Application Component.Owner maps to Application Component.Owner

Anything whose name doesn’t appear in the new metamodel has nowhere to go.

That makes migration well suited to moving between versions of the same metamodel, or to a metamodel deliberately built to replace another. It is a poor fit for switching between unrelated notations, where almost nothing will match.

Read the report

The preview shows a summary followed by two lists.

Summary

Message	Meaning
All classifiers and properties resolved. Ready to apply.	Everything maps. This is the clean case.
N classifier(s) unresolved	N element types have no match in the new metamodel. Apply is blocked.
N property value(s) will be deleted	Those properties don’t exist in the new metamodel. Apply is allowed, and the values are destroyed.

Classifiers

One row per element type in use, with a coloured dot:

• Green — Business Actor → Business Actor (14 instances). Matched, and the count tells you how much rides on it.
• Red — Value Stream — not found (6 instances). No element type of that name in the new metamodel.

Any red row blocks the migration. Farkitect will not orphan model elements by leaving them classified against a type that is going away.

Properties

One row per property that has values, again with a dot:

• Green — the property exists in the new metamodel and its values move across.
• Amber — the property has no match. Those values will be deleted when you apply.

Amber rows do not block Apply. They are the thing to read most carefully, because this is the only place in the migration where data is destroyed rather than remapped.

If a classifier is unresolved

You have three options:

Option	How
Add the missing type to the new metamodel, with the same name	See How to create an element type
Rename the type in the new metamodel so the names agree	Names must match exactly
Reclassify or delete the affected M1 elements first	The instance count in the report tells you how many are involved

Then preview again.

What Apply actually changes

When you click Apply Migration, Farkitect:

1. Repoints every matched element at its new element type
2. Repoints every matched property value at its new property
3. Deletes property values whose property had no match — the amber rows
4. Swaps the import on the M1 package from the old metamodel to the new one
5. Updates diagrams whose notation pointed at the old metamodel

Your elements, relationships, diagrams and layouts are otherwise untouched. Nothing is renamed or moved.

Before you migrate

Export the package first. Right-click it in the Explorer → Export Package… and keep the .farki file. Migration has no undo, and an export is a complete, importable snapshot. See How to export a package.

This matters most when the report shows amber property rows, since those values do not exist anywhere afterwards.

Which metamodels can I migrate to?

The Target Metamodel list shows metamodels marked as standard or common, excluding the one you’re moving away from.

If the metamodel you want isn’t listed, it’s most likely because it isn’t marked as a standard metamodel. Import it from the Farketplace, or check its package kind.

After migrating

• Run the integrity checker to confirm the model is consistent
• Check a diagram or two — nodes should render with the new metamodel’s notation
• Spot-check a few elements in the Properties panel to confirm their properties came across

Related

• How to upgrade a metamodel — a new version of the same metamodel, in place
• How to use the M2 lifecycle — usage tracking, what deleting a type does, and what else changes safely
• How to declare package imports
• How to export a package