---
title: "Evolution and migrations"
url: https://developers.dagio.ai/migrations/
---

# Evolution and migrations

   
                                 
                                                                  
                  
                
          
   

## Describe the change

Adding a Field, changing its type and removing a relation have different effects. Before activating a new definition, inspect affected data, views, Actions and work. Stable identities make changes recognizable.

| Change | Expected analysis | Verification |
| --- | --- | --- |
| Add a Field | Initial value and required behavior | Creation and existing records |
| Change a type | Compatibility and value transformation | Data and controls |
| Rename a key | References and identity | Queries, views and Actions |
| Change a relation | Objects and cardinality | Selection and reverse links |
| Modify a Flow | Ongoing runs and results | Version and recovery |

## Prepare and review

Changes identify scope, necessary transformations and conflicts. A preview lets you examine effects before activation. Human content must not be rewritten merely because presentation changed.

## Example

You require Email for new clients. Historical records without email must be identified and handled according to the chosen policy. Adding form validation alone does not make existing data conformant.

## Activate and inspect

After application, verify affected objects and journeys. Installed versions, migration operations and diagnostics explain the result. Older contracts retain their interpretation instead of silently accepting newer properties.

For a published upgrade, choose the exact version and then the destination of each Space. The
review distinguishes keeping current behaviour from adapting to the new version; adapting a Space
requires authority over its content. Declared names stay those of the source application, even if
the new version’s destinations have different names. An uncertain response resumes the same
confirmation. After the upgrade is recorded, retry only opening the application if that fails:
do not confirm again. Access to the new guide that needs restoration is reported separately from
the recorded upgrade.

<!-- surface-examples:start -->

## Applied examples : Evolve an existing record

Preserve Field keys and compare the new presentation before applying it to instances.

### Configuration

Fragment placed in `presentation.recordProfiles[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-record-profile/).

```json
{
  "key": "client",
  "definitionPaths": [
    "workspace/clients/surface/client"
  ],
  "editActionKey": "edit-client",
  "identity": {
    "title": {
      "kind": "field",
      "fieldPath": "fields/company"
    },
    "avatar": {
      "kind": "initials",
      "maximumLetters": 2
    },
    "subtitle": {
      "kind": "field",
      "fieldPath": "fields/status"
    }
  },
  "valueLabels": [
    {
      "fieldPath": "fields/status",
      "values": [
        {
          "value": "prospect",
          "label": "Prospect"
        },
        {
          "value": "active",
          "label": "Active"
        }
      ]
    }
  ],
  "card": {
    "summary": {
      "kind": "field",
      "fieldPath": "fields/notes"
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "metricKeys": [],
    "openLabel": "Open client"
  },
  "queryBindings": [],
  "metrics": [],
  "detail": {
    "primaryActionKey": null,
    "creationActionKeys": [],
    "actionKeys": [],
    "sections": [
      {
        "kind": "fields",
        "key": "follow-up",
        "label": "Client follow-up",
        "fieldPaths": [
          "fields/notes",
          "fields/status"
        ]
      }
    ],
    "settings": {
      "fieldPaths": [
        "fields/email"
      ]
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "relatedGroups": [],
    "primaryActionLabel": null
  }
}
```

### Variation and connection

Fragment placed in `forms[]`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-model-foundation/).

```json
{
  "contract": "WorkspaceForm@2",
  "key": "edit-client",
  "label": "Edit client",
  "actionKey": "edit-client",
  "targetDefinitionPath": "workspace/clients/surface/client",
  "mode": "edit",
  "fields": [
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "company",
      "label": "Company",
      "input": "text",
      "binding": {
        "kind": "field",
        "fieldKey": "company"
      },
      "required": true,
      "ruleKeys": [],
      "options": []
    },
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "status",
      "label": "Status",
      "input": "choice",
      "binding": {
        "kind": "field",
        "fieldKey": "status"
      },
      "required": true,
      "ruleKeys": [],
      "options": [
        "prospect",
        "active"
      ]
    },
    {
      "contract": "WorkspaceFormControl@2",
      "repeatable": false,
      "key": "notes",
      "label": "Notes",
      "input": "multiline",
      "binding": {
        "kind": "field",
        "fieldKey": "notes"
      },
      "required": false,
      "ruleKeys": [],
      "options": []
    }
  ],
  "ruleKeys": []
}
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Target object
2. Proposed change
3. Checks
4. Confirm

<!-- surface-examples:end -->