Improved migrations doc (#3296)

* Imroved migrations doc

* Manual changes

* Update docs/content_management/data_migration/importing_data.md

Co-authored-by: julitafalcondusza <117284672+julitafalcondusza@users.noreply.github.com>

---------

Co-authored-by: julitafalcondusza <117284672+julitafalcondusza@users.noreply.github.com>

Author: mnocon

code_samples/data_migration/examples/create_blog_post_ct.yaml

@@ -4,6 +4,14 @@
     metadata:
         identifier: blog_post
         mainTranslation: eng-GB
+        remoteId: blog_post_content_type
+        creatorId: 14
+        nameSchema: '<title>'
+        urlAliasSchema: '<title>'
+        container: true
+        defaultAlwaysAvailable: true
+        defaultSortField: 2 # Location::SORT_FIELD_PUBLISHED
+        defaultSortOrder: 0 # Location::SORT_ORDER_DESC
         contentTypeGroups:
             - Content
         translations:

code_samples/data_migration/examples/create_content_options.yaml

@@ -0,0 +1,25 @@
+-
+    type: content
+    mode: create
+    metadata:
+        contentType: folder
+        mainTranslation: eng-GB
+        creatorId: 14
+        modificationDate: '2025-06-01T10:00:00+00:00'
+        publicationDate: '2025-06-01T10:00:00+00:00'
+        remoteId: options_folder
+        alwaysAvailable: true
+        section:
+            identifier: standard
+    location:
+        parentLocationId: 2
+        # parentLocationRemoteId: root_location
+        locationRemoteId: options_folder_location
+        hidden: false
+        priority: 10
+        sortField: 9 # Location::SORT_FIELD_NAME
+        sortOrder: ASC
+    fields:
+        -   fieldDefIdentifier: name
+            languageCode: eng-GB
+            value: 'Folder with all options'

code_samples/data_migration/examples/create_product_availability.yaml

@@ -0,0 +1,7 @@
+-
+    type: product_availability
+    mode: create
+    product_code: ergo_desk
+    is_available: true
+    is_infinite: false
+    stock: 100

code_samples/data_migration/examples/service_call_step.yaml

@@ -0,0 +1,8 @@
+-
+    type: service_call
+    mode: execute
+    service: App\Migration\ContentImporter
+    method: import
+    arguments:
+        - content.csv
+        - 42

code_samples/data_migration/examples/update_content.yaml

@@ -0,0 +1,21 @@
+-
+    type: content
+    mode: update
+    match:
+        field: content_remote_id
+        value: options_folder
+    metadata:
+        mainLanguageCode: eng-GB
+        name: 'Updated folder'
+        initialLanguageCode: eng-GB
+        remoteId: f5c88a2209584891056f987fd965b0ba
+        mainLocationId: 5
+        creatorId: 14
+        ownerId: 14
+        publishedDate: '2002-10-06T15:19:56+00:00'
+        alwaysAvailable: false
+        modificationDate: '2025-06-15T10:00:00+00:00'
+    fields:
+        -   fieldDefIdentifier: name
+            languageCode: eng-GB
+            value: 'Updated folder'

code_samples/data_migration/examples/update_user.yaml

@@ -5,4 +5,6 @@
         field: login
         value: admin
     metadata:
+        email: admin@example.com
+        enabled: true
         password: '###XXX env("ADMIN_PASSWORD") XXX###'

docs/content_management/data_migration/data_migration_actions.md

@@ -50,6 +50,7 @@ When executed, this migration:
 
 The following migration actions are available out of the box:
 
+- `assign_dashboard_to_user` (Content Create)
 - `assign_object_state` (Content Create)
 - `assign_parent_location` (Content Create / Update)
 - `assign_section` (Content Update)
@@ -91,6 +92,13 @@ mode: Update
         - { action: assign_section, identifier: 'media' }
 ```
 
+When creating a [dashboard](customize_dashboard.md) content item, you can assign it to a specific user, identified by their login:
+
+``` yaml
+    actions:
+        - { action: assign_dashboard_to_user, value: admin }
+```
+
 ### Content types
 
 mode: Create

docs/content_management/data_migration/importing_data.md

@@ -50,6 +50,7 @@ The following data migration step modes are available:
 | `action_configuration` | ✔ | ✔ | ✔ |          |          |
 | `attribute`            | ✔ | ✔ | ✔ |          |          |
 | `attribute_group`      | ✔ | ✔ | ✔ |          |          |
+| `company`              | ✔ |          |          |          |          |
 | `content_type`         | ✔ | ✔ | ✔ |          |          |
 | `content_type_group`   | ✔ | ✔ | ✔ |          |          |
 | `content`              | ✔ | ✔ | ✔ |          |          |
@@ -71,16 +72,21 @@ The following data migration step modes are available:
 | `segment`              | ✔ | ✔ | ✔ |          |          |
 | `segment_group`        | ✔ | ✔ | ✔ |          |          |
 | `setting`              | ✔ | ✔ | ✔ |          |          |
+| `shipping_method`      | ✔ |          |          |          |          |
 | `user`                 | ✔ | ✔ |          |          |          |
 | `user_group`           | ✔ | ✔ | ✔ |          |          |
 
 Additionally, the following special migration types are available:
 
-| `type`                 | `execute` |
-|------------------------|:---------:|
-| `repeatable`           | ✔  |
-| `sql`                  | ✔  |
-| `try_catch`            | ✔  |
+| `type`         | `mode`                        |
+|----------------|-------------------------------|
+| `reference`    | `load`, `save`, `set`, `list` |
+| `repeatable`   | `create`                      |
+| `service_call` | `execute`                     |
+| `sql`          | `execute`                     |
+| `try_catch`    | `execute`                     |
+
+For more information about the `reference` type, see [References](managing_migrations.md#references).
 
 ### Repeatable steps
 
@@ -112,6 +118,8 @@ In the example above, the expression is enclosed in `###` and the repeated strin
 !!! note
 
     Iteration counter is assigned to `i` by default, but you can modify it in the `iteration_counter_name` setting.
+    The counter starts at `0` by default.
+    You can change this with the `iteration_counter_starting_value` setting.
 
 #### Repeatable steps with items
 
@@ -209,6 +217,25 @@ If the exception matches, it's caught and the migration step continues or stops
 The migration step is marked as successful and the migration process continues.
 Non-matching exceptions throw immediately, halting the migration process and returning an error.
 
+### Service calls
+
+You can call a method of a service by using the `service_call` migration type.
+Use it when a migration requires custom logic that isn't covered by the built-in migration types.
+
+A `service_call` migration requires the `service` and `method` properties, and accepts an optional `arguments` list passed to the method:
+
+```yaml
+[[= include_file('code_samples/data_migration/examples/service_call_step.yaml') =]]
+```
+
+You can only call services that are explicitly listed under the `ibexa_migrations.callable_services` configuration key:
+
+```yaml
+ibexa_migrations:
+    callable_services:
+        - App\Migration\ContentImporter
+```
+
 ### Expression syntax
 
 You can use [Symfony expression syntax]([[= symfony_doc =]]/reference/formats/expression_language.html) in data migrations, like in [repeatable steps](#repeatable-steps), where you can use it to generate varied content in migration steps.
@@ -300,6 +327,7 @@ The following examples show what data you can import using data migrations.
 The following example shows how to create a content type with two field definitions.
 
 The required metadata keys are: `identifier`, `mainTranslation`, `contentTypeGroups` and `translations`.
+The example also shows the optional metadata keys: `nameSchema`, `urlAliasSchema`, `container`, `defaultAlwaysAvailable`, `defaultSortField`, `defaultSortOrder`, `remoteId`, and `creatorId`.
 
 The default values of field definition properties mirror the underlying PHP API, for example:
 
@@ -314,7 +342,8 @@ The default values of field definition properties mirror the underlying PHP API,
 
 The following example shows how to create two content items: a folder and an article inside it.
 
-When creating a content item, three metadata keys are required: `contentType`, `mainTranslation`, and `parentLocationId`.
+When creating a content item, three metadata keys are required: `contentType`, `parentLocationId`, and `mainTranslation`.
+The `mainTranslation` property sets content item's main language.
 
 To use the location ID of the folder, which is created automatically by the system, you can use a [reference](managing_migrations.md#references).
 In this case you assign the `parent_folder_location_id` reference name to the location ID, and then use it when creating the article.
@@ -323,6 +352,22 @@ In this case you assign the `parent_folder_location_id` reference name to the lo
 [[= include_file('code_samples/data_migration/examples/create_parent_and_child_content.yaml') =]]
 ```
 
+The following example shows the optional `metadata` and `location` properties that you can set when creating a content item.
+Instead of `parentLocationId`, you can identify the parent location with `parentLocationRemoteId`.
+`sortField` takes the numeric value of one of the `SORT_FIELD_*` constants from the [`Location` class](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-Location.html), and `sortOrder` takes `ASC` or `DESC`, case insensitive:
+
+``` yaml
+[[= include_file('code_samples/data_migration/examples/create_content_options.yaml') =]]
+```
+
+Use the `update` mode to modify an existing content item.
+You can match the content item by `content_remote_id`, `location_id`, `parent_location_id`, or `content_type_identifier`.
+All `metadata` keys are optional: [`initialLanguageCode`](creating_content.md#translating-content), [`mainLanguageCode`](content_model.md#content-information), `creatorId`, `remoteId`, `alwaysAvailable`, `mainLocationId`, `modificationDate`, `publishedDate`, `name`, and `ownerId`.
+
+``` yaml
+[[= include_file('code_samples/data_migration/examples/update_content.yaml') =]]
+```
+
 Use the `delete` mode to delete content items:
 
 ``` yaml
@@ -412,7 +457,8 @@ You can use an [action](data_migration_actions.md) to assign a role to the user.
 [[= include_file('code_samples/data_migration/examples/create_user.yaml') =]]
 ```
 
-You can also update user information, including passwords:
+You can also update the user's email, enabled status, and password.
+All `metadata` keys are optional:
 
 ``` yaml
 [[= include_file('code_samples/data_migration/examples/update_user.yaml') =]]
@@ -503,6 +549,16 @@ The following example shows how to create a price for a product identified by it
 [[= include_file('code_samples/data_migration/examples/create_product_price.yaml') =]]
 ```
 
+#### Product availability
+
+The following example shows how to define the availability and stock of a product identified by its code:
+
+``` yaml
+[[= include_file('code_samples/data_migration/examples/create_product_availability.yaml') =]]
+```
+
+When `is_infinite` is set to `true`, `stock` must be `null`.
+
 #### Customer groups
 
 The following example shows how to create a customer group with a defined global price discount:

docs/content_management/data_migration/managing_migrations.md

@@ -167,17 +167,36 @@ The order of migration steps matters - they are executed sequentially from top t
     filename: 'references/new_references.yaml'
 ```
 
+You can also set a reference value manually with the `set` mode, and use the `list` mode to print all references collected so far to the migration log:
+
+```yaml
+-
+    type: reference
+    mode: set
+    name: parent_location_id
+    value: 2
+
+-
+    type: reference
+    mode: list
+```
+
 ## Available reference types
 
 - `content`
-    - content_id
-    - location_id
-    - path
+    - `content_id`
+    - `location_id`
+    - `path`
 - `content_type`
-    - content_type_id
+    - `content_type_id`
 - `language`
-    - language_id
+    - `language_id`
+    - `language_code`
 - `role`
-    - role_id
+    - `role_id`
+- `section`
+    - `section_id`
+- `user`
+    - `user_id`
 - `user_group`
-    - user_group_id
+    - `user_group_id`