Migration

A migration definition describes how data should be imported from a legacy system into the platform. It is published via GET /metadata/{tenantId}/migrationDefinition and consumed by an external migration tool that performs the actual import.

MigrationDefinition

{
  "migrationType": "MyLegacyERP",
  "parameters": [
    { "name": "apiUrl" },
    { "name": "apiKey" }
  ],
  "steps": [...],
  "valueMap": {
    "MALE": "male",
    "FEMALE": "female"
  },
  "mnRelations": [...]
}

Property	Type	Description
migrationType	string	Identifier of the legacy system (e.g. "MyLegacyERP").
parameters	ValueType[]	Configuration parameters the migration tool needs (e.g. API URL, credentials).
steps	MigrationStep[]	Ordered list of entity mappings. Each step maps one legacy entity type to a target class.
valueMap	object	Global value substitutions applied across all steps. Maps legacy codes to new values (e.g. enum key renames).
mnRelations	MnRelationMapping[]	Many-to-many join table mappings.

MigrationStep

Each step maps one legacy entity type (e.g. a database table or export file) to a target class.

{
  "source": "EMPLOYEES",
  "target": "commons.person",
  "fields": [...],
  "relations": [...]
}

Property	Type	Description
source	string	Legacy entity identifier (e.g. table name or export filename).
target	TypeFQN	Target class.
prefix	string	Optional namespace prefix for disambiguation.
fields	FieldMapping[]	Field mappings for this entity.
relations	RelationMapping[]	Relation mappings for this entity.

FieldMapping

Maps a single field from the legacy entity to a value type on the target class.

{ "source": "FIRST_NAME", "target": "firstName" }

{ "source": "EMP_STATUS", "target": "status", "defaultValue": "active" }

Property	Type	Description
source	string	Field name in the legacy entity.
target	string	Target value type field name.
type	string	Type hint. Use "OBJECT" for nested object fields (handled separately by the migration tool).
defaultValue	string	Fallback value when the source field is absent or empty.
key	boolean	When true, this field is used by the migration tool for duplicate detection.

RelationMapping

Maps a relation field from the legacy entity to a target relation type.

{ "source": "DEPARTMENT_ID", "target": "my-project.department" }

{ "source": "TAG_IDS", "target": "my-project.tag", "multiple": true }

Property	Type	Description
source	string	Relation field name in the legacy entity.
target	TypeFQN	Target relation type.
multiple	boolean	When true, this is a many-to-many relation and the REST endpoint uses the plural form.
prefix	string	Disambiguation prefix.

MnRelationMapping

Maps a many-to-many join table in the legacy system to a pair of relation endpoints.

{
  "sourceFrom": "EMPLOYEE_ID",
  "targetFrom": "commons.person",
  "sourceTo": "PROJECT_ID",
  "targetTo": "my-project.project"
}

Property	Type	Description
sourceFrom	string	Foreign key column for the "from" side in the legacy join table.
targetFrom	TypeFQN	Target "from" side.
sourceTo	string	Foreign key column for the "to" side in the legacy join table.
targetTo	TypeFQN	Target "to" side.

Complete example

{
  "class": "my-project.migrationConfig",
  "type": "NONE",

  "migration": {
    "migrationType": "LegacyHR",
    "parameters": [
      { "name": "exportPath" }
    ],
    "valueMap": {
      "M": "male",
      "F": "female",
      "PERM": "permanent",
      "TEMP": "fixedTerm"
    },
    "steps": [
      {
        "source": "persons",
        "target": "commons.person",
        "fields": [
          { "source": "first_name", "target": "firstName", "key": true },
          { "source": "last_name", "target": "lastName", "key": true },
          { "source": "gender", "target": "gender" },
          { "source": "email", "target": "emailAddress" }
        ]
      },
      {
        "source": "agreements",
        "target": "my-project.employmentAgreement",
        "fields": [
          { "source": "job_title", "target": "jobTitle" },
          { "source": "salary", "target": "salary" },
          { "source": "contract_type", "target": "contractType" }
        ],
        "relations": [
          { "source": "employee_id", "target": "commons.person" },
          { "source": "company_id", "target": "commons.company" }
        ]
      }
    ]
  }
}