Migrate Blueprint Data

When evolving your software catalog, you may need to migrate existing entities to reflect changes in your blueprint structure. Port provides a simple approach to migrate all entities of a blueprint efficiently and safely.

When to migrate data

Data migration becomes necessary when you need to:

• Transform data format: Change property values and/or merge and seperate properties in existing blueprints.
• Update relations: Modify existing relations between blueprints.

Blueprint schema evolution

After migrating data, if you want to revert the changes, you will need to create a new migration from scratch.

How to migrate data

Using the UI

To migrate data using Port UI, go to the Builder page of your portal and select your desired blueprint.
Click on the ... button of the blueprint you want to migrate, and select Migrate data from the dropdown menu.

Below are some example screenshots to help you understand the migration process.

Selecting the source blueprint

In this step, you choose the blueprint you want to migrate data from. This is done from the the Builder Page, where you can access the migration option from the actions menu.

Locking operations

We recommend locking updates to the blueprint during migration to ensure data integrity as updates might fail for entities registered during the migrations.

Mapping properties and relations

Here, you are presented with a mapping interface. You can match properties and relations from the source blueprint to those in the target blueprint. This ensures that your data is correctly transformed during the migration.

Reviewing the migration plan

Before executing the migration, you can review a summary of the planned changes. This includes a preview of how entities will look after migration, allowing you to verify that all mappings are correct and JQ checks out.

Migration progress and completion

During the migration, you can monitor progress in real time. Once the migration is complete, you will see a confirmation message and can review the results directly in the UI.

Using the API

You can create migrations programmatically using the Create a Migration API.

Request body schema

{
  "sourceBlueprint": "string",
  "mapping": {
    "blueprint": "string",
    "filter": "string (optional)",
    "itemsToParse": "string (optional)",
    "entity": {
      "identifier": "jq expression",
      "title": "jq expression",
      "icon": "string (optional)",
      "team": "string (optional)",
      "properties": {
        "propertyName": "jq expression"
      },
      "relations": {
        "relationName": "jq expression"
      }
    }
  }
}

Field	Description
sourceBlueprint	The identifier of the blueprint to migrate data from.
mapping.blueprint	The identifier of the target blueprint (can be the same as source for in-place transforms).
mapping.filter	Optional conditions to filter which entities to migrate.
mapping.itemsToParse	Optional JQ query to create multiple entities from a single source entity.
mapping.entity	Defines how to map source entity data to target entity fields using JQ expressions.

Example: Copy data to a new property

This example copies data from oldProperty to newProperty within the same blueprint:

curl -X POST "https://api.getport.io/v1/migrations" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceBlueprint": "service",
    "mapping": {
      "blueprint": "service",
      "entity": {
        "identifier": ".identifier",
        "title": ".title",
        "properties": {
          "newProperty": ".properties.oldProperty"
        }
      }
    }
  }'

Example: Change a property type (array to object)

Since you cannot directly change a property's type, you need to:

1. Create a new property with the desired type.
2. Use the Migration API to transform and copy the data.
3. Delete the old property.
4. Optionally rename the new property.

For example, to convert a tags array (["prod", "critical"]) to a tagsObject object ({"env": "prod", "priority": "critical"}):

Step 1: Add a new tagsObject property with type object to your blueprint.

Step 2: Run the migration with a JQ transformation:

curl -X POST "https://api.getport.io/v1/migrations" \
  -H "Authorization: Bearer $PORT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceBlueprint": "service",
    "mapping": {
      "blueprint": "service",
      "entity": {
        "identifier": ".identifier",
        "title": ".title",
        "properties": {
          "tagsObject": ".properties.tags | if . then {env: .[0], priority: .[1]} else {} end"
        }
      }
    }
  }'

Step 3: After verifying the migration succeeded, delete the old tags property from the blueprint.

Step 4: Optionally rename tagsObject to tags.

Property type changes

The Migration API migrates data between properties - it does not change the schema of existing properties. To change a property's type, you must create a new property with the correct type first. See Change a property's type for more details.

Troubleshoot migration issues

If all entities fail to migrate, the migration status will display "Migration failed" in red.
If only some entities fail, the status will show "Migrated with errors".
You can hover over the status to see a tooltip indicating how many entities failed.

Example: If 3 out of 10 entities failed, hovering over "Migrated with errors" will show "3 entities failed to migrate".