Skip to content
  • Documentation >
  • Content management >
  • Data migration >
  • Managing migrations

Managing migrations

Converting migration files

If you want to convert a file from the format used by the Kaliop migration bundle to the current migration format, use the ibexa:migrations:kaliop:convert command.

The source file must use Kaliop mode and type combinations. The converter handles Kaliop types that are different from Ibexa types.

1
php bin/console ibexa:migrations:kaliop:convert --input=kaliop_format.yaml --output=ibexa_format.yaml

You can also convert multiple files using ibexa:migrations:kaliop:bulk-convert:

1
php bin/console ibexa:migrations:kaliop:bulk-convert --recursive kaliop_files ibexa_files

If you do not specify the output folder, the command overwrites the input files.

Adding migration files

Use the ibexa:migrations:import command to add files to the migration folder defined in configuration (by default, src/Migrations/Ibexa/migrations).

1
php bin/console ibexa:migrations:import my_data_export.yaml

Checking migration status

To check the status of migration files in the migration folder defined in configuration, run the following command:

1
php bin/console ibexa:migrations:status

The command lists the migration files and indicates which of them have already been migrated.

Migration folders

The default migration folder is src/Migrations/Ibexa/migrations.

You can configure a different folder by using the following settings:

1
2
3
ibexa_migrations:
    migration_directory: %kernel.project_dir%/src/Migrations/MyMigrations/
    migrations_files_subdir: migration_files

Multi-repository scenario

In multi-repository environments, where data for different websites is stored in separate databases, you can migrate such databases separately, to prevent the migration processes from affecting each other.

The ibexa_migrations.migration_directory setting accepts a placeholder within a path. The placeholder is dynamically replaced by a name of the repository that you want to migrate, based on the selected SiteAccess.

1
2
3
ibexa_migrations:
    migration_directory: '%kernel.project_dir%/data/<repository>'
    ...

Then, when you run the migration command, you must use the --siteaccess option and provide the name of the SiteAccess that you want to migrate.

Preview configuration

You can get default configuration along with option descriptions by executing the following command:

1
bin/console config:dump-reference ibexa_migrations

References

References are key-value pairs necessary when one migration depends on another.

Since some migrations generate object properties (like IDs) during their execution, which cannot be known in advance, references provide migrations with the ability to use previously created object properties in further migrations. They can be subsequently used by passing them in their desired place with reference: prefix.

The example below creates a content item of type "folder", and stores its Location path as "ref_path__folder__media". Then this reference is reused as part of a new role, as a limitation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
-
    type: content
    mode: create
    metadata:
        contentType: folder
        mainTranslation: eng-US
        alwaysAvailable: true
        section: 3
        objectStates: {  }
    location:
        parentLocationId: 1
        hidden: false
        sortField: !php/const Ibexa\Contracts\Core\Repository\Values\Content\Location::SORT_FIELD_NAME
        sortOrder: 1
        priority: 0
    fields:
        -
            fieldDefIdentifier: name
            languageCode: eng-US
            value: Media
        # - ...
    actions: {  }
    references:
        -
            name: ref__content__folder__media
            type: content_id
        -
            name: ref_location__folder__media
            type: location_id
        -
            name: ref_path__folder__media
            type: path

-
    type: role
    mode: create
    metadata:
        identifier: foo
    policies:
        -
            module: content
            function: 'read'
            limitations:
                -
                    identifier: Subtree
                    values: ['reference:ref_path__folder__media']

By default, reference files are located in a separate directory src/Migrations/Ibexa/references (see previewing reference ibexa_migrations.migration_directory and ibexa_migrations.references_files_subdir options).

Reference files are NOT loaded by default. A separate step (type: "reference", mode: "load", with filename as "value") is required. Similarly, saving a reference file is done using type: "reference", mode: "save" step, with filename.

For example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
-
    type: reference
    mode: load
    filename: 'references.yaml'

-
    type: reference
    mode: save
    # You can also use 'references.yaml', in this case it is overridden
    filename: 'new_references.yaml'

Note

You don't need to save references if they are used in the same migration file. References are stored in memory during migration, whether they are used or not.

Available reference types

  • content
    • content_id
    • location_id
    • path
  • content_type
    • content_type_id
  • language
    • language_id
  • role
    • role_id
  • user_group
    • user_group_id