From 8d15f94a5d054d03174a4c008af4a27e72e01dbd 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 1/5] 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` From 2890e4bef63c8a4d67914f2e6611049ce4b08052 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 20 Jan 2026 12:55:51 +0100 Subject: [PATCH 2/5] Update docs/content_management/data_migration/managing_migrations.md --- docs/content_management/data_migration/managing_migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/data_migration/managing_migrations.md b/docs/content_management/data_migration/managing_migrations.md index 0ace59a3fd..c907817fda 100644 --- a/docs/content_management/data_migration/managing_migrations.md +++ b/docs/content_management/data_migration/managing_migrations.md @@ -130,7 +130,7 @@ Reference files are located in a separate directory `src/Migrations/Ibexa/refere 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. -References must be loaded **before** they can be used in the same migration file. +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 From fbad0b4de377a9605c7acc45049a8432707d8204 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 20 Jan 2026 13:23:55 +0100 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Thorsten Reiter <34274688+reithor@users.noreply.github.com> --- docs/content_management/data_migration/managing_migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/data_migration/managing_migrations.md b/docs/content_management/data_migration/managing_migrations.md index c907817fda..7cf4ac7615 100644 --- a/docs/content_management/data_migration/managing_migrations.md +++ b/docs/content_management/data_migration/managing_migrations.md @@ -128,7 +128,7 @@ 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. +Similarly, saving a reference file is done using `type: reference`, `mode: save` step, with filename. 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. From 8e52d2321eb4b70027cd7b68272985185b6e7d3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 20 Jan 2026 13:32:48 +0100 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> --- .../data_migration/managing_migrations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content_management/data_migration/managing_migrations.md b/docs/content_management/data_migration/managing_migrations.md index 7cf4ac7615..bc78add556 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 the content item of type "folder" named "Media" below the root, and stores its location path as `"ref__path__folder__media"` to use it later while creating a related role. Then this reference is reused as part of a new role, as a limitation. ```yaml @@ -127,10 +127,10 @@ By default, references are stored in memory and can be reused within the same mi 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. +Reference files **aren't** loaded by default. A separate step (`type: reference`, `mode: load`, with `filename` with a relative path as value) is required. Similarly, saving a reference file is done using `type: reference`, `mode: save` step, with filename. -References must be loaded **before** they can be used in the same migration file. +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 From e52ed91918e5e9ac5f2c4a3c1acd0c7a5cf8f3d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 20 Jan 2026 17:40:40 +0100 Subject: [PATCH 5/5] Added mention about overwriting --- docs/content_management/data_migration/managing_migrations.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content_management/data_migration/managing_migrations.md b/docs/content_management/data_migration/managing_migrations.md index bc78add556..62f370d3bc 100644 --- a/docs/content_management/data_migration/managing_migrations.md +++ b/docs/content_management/data_migration/managing_migrations.md @@ -126,6 +126,7 @@ By default, references are stored in memory and can be reused within the same mi 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). +When saving references, existing files with the same name are overwritten. Reference files **aren't** loaded by default. A separate step (`type: reference`, `mode: load`, with `filename` with a relative path as value) is required. Similarly, saving a reference file is done using `type: reference`, `mode: save` step, with filename.