From 9b178764052e842ef79fe25117071ade00bdc18a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Mon, 15 Dec 2025 23:39:05 +0100 Subject: [PATCH] Clarified migration references --- .../data_migration/exporting_data.md | 4 +-- .../data_migration/managing_migrations.md | 33 +++++++++++-------- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/content_management/data_migration/exporting_data.md b/docs/content_management/data_migration/exporting_data.md index 7cb301514d..dce3baa589 100644 --- a/docs/content_management/data_migration/exporting_data.md +++ b/docs/content_management/data_migration/exporting_data.md @@ -56,10 +56,10 @@ Below you can see part of the output of the default [[= product_name =]] install name: ref__content__user_group__users type: content_id - - name: ref_location__user_group__users + name: ref__location__user_group__users type: location_id - - name: ref_path__user_group__users + name: ref__path__user_group__users type: path ``` diff --git a/docs/content_management/data_migration/managing_migrations.md b/docs/content_management/data_migration/managing_migrations.md index f067e6f96a..0ace59a3fd 100644 --- a/docs/content_management/data_migration/managing_migrations.md +++ b/docs/content_management/data_migration/managing_migrations.md @@ -69,7 +69,7 @@ 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"`. +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. ```yaml @@ -100,10 +100,10 @@ Then this reference is reused as part of a new role, as a limitation. name: ref__content__folder__media type: content_id - - name: ref_location__folder__media + name: ref__location__folder__media type: location_id - - name: ref_path__folder__media + name: ref__path__folder__media type: path - @@ -118,35 +118,40 @@ Then this reference is reused as part of a new role, as a limitation. limitations: - identifier: Subtree - values: ['reference:ref_path__folder__media'] + values: ['reference:ref__path__folder__media'] ``` -By default, reference files are located in a separate directory `src/Migrations/Ibexa/references` (for more information, see [previewing reference](#preview-configuration) `ibexa_migrations.migration_directory` and `ibexa_migrations.references_files_subdir` options). +By default, references are stored in memory and can be reused within the same migration file without additional steps. + +To reuse them across different migration files, you can save them to disk. +Reference files are located in a separate directory `src/Migrations/Ibexa/references` (for more information, see [previewing reference](#preview-configuration) `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: +References must be loaded **before** they can be used in the same migration file. +The order of migration steps matters - they are executed sequentially from top to bottom. ```yaml - type: reference mode: load - filename: 'references.yaml' + filename: 'references/references.yaml' # Load references created by other migrations +# Use them +- + type: content + mode: create + # ... + +# Save any new references if needed - type: reference mode: save - # You can also use 'references.yaml', in this case it's overridden - filename: 'new_references.yaml' + filename: 'references/new_references.yaml' ``` -!!! note - - You don't need to save references if they're used in the same migration file. - References are stored in memory during migration, whether they're used or not. - ## Available reference types - `content`