From 5c9742aef623d55db556e14d58e2de2009763be9 Mon Sep 17 00:00:00 2001 From: Mauricio Dinarte Date: Tue, 15 Aug 2023 11:44:37 -0600 Subject: [PATCH] Update articles --- 02.md | 2 +- 03.md | 2 +- 04.md | 2 +- 06.md | 14 +++++++------- 07.md | 19 +++++++++++++++---- 5 files changed, 25 insertions(+), 14 deletions(-) diff --git a/02.md b/02.md index a48d9f0..6efd93c 100644 --- a/02.md +++ b/02.md @@ -37,7 +37,7 @@ process: title: creative_title body: engaging_content destination: - plugin: "entity:node" + plugin: entity:node default_bundle: page ``` diff --git a/03.md b/03.md index 4dfc32d..4a927b8 100644 --- a/03.md +++ b/03.md @@ -42,7 +42,7 @@ process: plugin: default_value default_value: page destination: - plugin: 'entity:node' + plugin: entity:node ``` The above example sets the `type` property for all nodes in this migration to `page`, which is the machine name of the `Basic page` content type. Do not confuse the name of the plugin with the name of its configuration property as they happen to be the same: `default_value`. Also note that because `type` is manually set in the process section, the `default_bundle` key in the destination section is no longer required. You can see the latter being used in the example of the chapter 2. If `type` is defined in the `process` section and `default_bundle` in the `destination` section, the former takes precedence. diff --git a/04.md b/04.md index a8e5342..7022116 100644 --- a/04.md +++ b/04.md @@ -103,7 +103,7 @@ Another option is to connect to the database and check the table structures. For Looking at the source code or the database schema is arguably not straightforward. This information is included for reference to those who want to explore the Migrate API in more detail. You can look for migrations examples to see what subfields are available. -*Tip*: Many plugins are defined by classes whose name ends with the string `Item`. You can use your IDEs search feature to find the class using the name of the field as hint. Those classes would like in the `src/Plugin/Field/FieldType` folder of the module. +_Tip_: Many plugins are defined by classes whose name ends with the string `Item`. You can use your IDEs search feature to find the class using the name of the field as hint. Those classes would like in the `src/Plugin/Field/FieldType` folder of the module. ## Default subfields diff --git a/06.md b/06.md index 87abd69..caab274 100644 --- a/06.md +++ b/06.md @@ -87,23 +87,23 @@ _Note_: The focus of this section was [content entity](https://www.drupal.org/do We just mentioned that Migrate API triggers an entity delete action when rolling back a migration. This has another important side effect. Entity IDs (`nid`, `uid`, `tid`, `fid`, `mid`, etc.) are going to change every time you _rollback_ and _import_ again. Depending on auto generated IDs is generally not a good idea. But keep it in mind in case your workflow might rely on them. For example, if you are running migrations in a content staging environment, references to the migrated entities can break if their IDs change. Also, if you were to manually update the migrated entities to clean up edge cases, those changes would be lost if you _rollback_ and _import_ again. As described in the previous section, test data might remain in the system after a rollback so make sure to clean things up when deploying to production environments. -An alternative to rolling back a migration is to not execute this operation at all. Instead, you run an _import_ operation again using the `--update` flag. This tells the system that in addition to migrating unprocessed items from the source, you also want to update items that were previously imported using their current values. To do this, the Migrate API relies on _source identifiers_ and _map tables_. You might want to consider this option when your source changes overtime, when you have a large number of records to import, or when you want to execute the same migration many times on a schedule. +An alternative to rolling back a migration is to not execute this operation at all. Instead, you run an _import_ operation again using the `--update` flag. This tells the system that in addition to migrating unprocessed items from the source, you also want to update items that were previously imported using their current source values. To do this, the Migrate API relies on _source identifiers_ and _map tables_. You might want to consider this option when your source changes overtime, when you have a large number of records to import, or when you want to execute the same migration many times on a schedule. _Note_: On import operations, the Migrate API issues an entity save action. ## Tips for writing Drupal migrations -When working on migration projects, you might end up with many migration plugin files. They can set dependencies on each other. Each file might contain a significant number of field mappings. There are many things you can do to make Drupal migrations more straightforward. For example, practicing with different migration scenarios and studying working examples. As a reference to help you in the process of migrating into Drupal, consider these tips: +When working on migration projects, you might end up with many migration plugin files. They can set dependencies on each other. Each file might contain a significant number of field mappings. There are many things you can do to make Drupal migrations more straightforward. For example, practicing with different migration scenarios and studying working examples. As a reference, consider these tips for working on migration projects: - Start from an existing migration. Look for an example online that does something close to what you need and modify it to your requirements. - Pay close attention to the syntax of the YAML file. An extraneous space or wrong indentation level can break the whole migration. - Read the documentation to know which source, process, and destination plugins are available. One might exist already that does exactly what you need. -- Make sure to read the documentation for the specific plugins you are using. Many times a plugin offer optional configurations. Understand the tools at your disposal and find creative ways to combine them. +- Make sure to read the documentation for the specific plugins you are using. Many times a plugin offer optional configuration options. Understand the tools at your disposal and find creative ways to combine them. - Look for [contributed modules](https://www.drupal.org/project/project_module?f%5B0%5D=&f%5B1%5D=&f%5B2%5D=im_vid_3%3A64&f%5B3%5D=drupal_core%3A7234&f%5B4%5D=sm_field_project_type%3Afull&f%5B5%5D=&f%5B6%5D=&text=&solrsort=iss_project_release_usage+desc&op=Search) that might offer more plugins or upgrade paths from previous versions of Drupal. The Migrate ecosystem is vibrant and lots of people are contributing to it. -- When writing the migration pipeline, map one field at a time. Problems are easier to isolate if there is only one thing that could break at a time. +- When writing the migration plugin file, map one field at a time. Problems are easier to isolate if there is only one thing that could break at a time. - When mapping a field, work on one subfield at a time if possible. Some field types like images and addresses offer many subfields. Again, try to isolate errors by introducing individual changes each time. -- There is no need to do every data transformation using the Migrate API. When there are edge cases, you can manually update those after the automated migration is **completed**. That is, no more rollback operations. You can also clean up the source data in advance to make it easier to process in Drupal. -- Commit to your code repository any and every change that produces right results. That way you can go back in time and recover a partially working migration. +- There is no need to do every data transformation using the Migrate API. When there are edge cases, you can manually update those after the automated migration is **completed**. That is, no more rollback operations. You can also clean up the source data in advance to make it easier to process it in Drupal. +- Commit to your code repository any and every change that produces right results. That way you can go back in time and recover a partially working migration if things go wrong. - Learn about [debugging migrations](https://www.drupal.org/docs/8/api/migrate-api/debugging-migrations). We will talk about this topic in a future chapter. -- See help from the community. Migrate maintainers and enthusiasts are very active and responsive in the #migrate channel of Drupal slack. +- Seek help from the community. Migrate maintainers and enthusiasts are very active and responsive in the #migrate channel of Drupal slack. - If you feel stuck, take a break from the computer and come back to it later. Resting can do wonders in finding solutions to hard problems. diff --git a/07.md b/07.md index 75f0930..9a621c4 100644 --- a/07.md +++ b/07.md @@ -1,17 +1,28 @@ # Migrating files and images into Drupal -We have already covered two of many ways to migrate images into Drupal. One example allows you to set the image subfields manually. The other example uses a process plugin that accomplishes the same result using plugin configuration options. Although valid ways to migrate images, these approaches have an important limitation. The files and images are _not removed from the system upon rollback_. In the previous chapter, we talked further about this topic. Today, we are going to perform an image migration that will clear after itself when it is rolled back. Note that in Drupal images are a special case of files. Even though the example will migrate images, the same approach can be used to import any type of file. This migration will also serve as the basis for explaining migration dependencies in the next chapter. +We have already covered two of many ways to migrate images into Drupal. One example allows you to set the image subfields manually. The other example uses a process plugin that accomplishes the same result using plugin configuration options. Although valid ways to migrate images, these approaches have an important limitation. The files and images are _not removed from the system upon rollback_. We covered this topic in chapter 4. In this chapter, we will perform an image migration that will clear after itself when it is rolled back. Note that in Drupal images are a special case of files. Even though the example will migrate images, the same approach can be used to import any type of file. This migration will also serve as the basis for explaining migration dependencies in the next chapter. ## File entity migrate destination -All the examples so far have been about creating nodes. The migrate API is a full ETL framework able to write to different destinations. In the case of Drupal, the target can be other content entities like files, users, taxonomy terms, comments, etc. Writing to content entities is straightforward. For example, to migrate into files, the process section is configured like this: +All the examples so far have been about creating nodes. The migrate API is a full ETL framework able to write to different destinations. In the case of Drupal, the target can be other content entities like files, users, taxonomy terms, comments, media items, etc. Writing to content entities is straightforward. For example, to migrate into files, the process section is configured like this: ```yaml destination: - plugin: "entity:file" + plugin: entity:file ``` -You use a plugin whose name is `entity:` followed by the machine name of your target entity. In this case `file`. Other possible values are `user`, `taxonomy_term`, and `comment`. Remember that each migration definition file can only write to one destination. +You use a plugin whose name is `entity:` followed by the machine name of your target entity. In this case `file`. Other possible values are `user`, `taxonomy_term`, and `comment`. Remember that each migration definition file can only write to one destination. Read more about [destination plugins and their configuration in this article](https://understanddrupal.com/blog/drupal-migrations-reference-list-configuration-options-destination-plugins/). + +_Tip_: Use the commands below to which all destination plugins known to your current installation. They will depend on which modules are currently enabled. + +```console +# List of migrate destination plugin ids. +$ drush php:eval "print_r(array_keys(\Drupal::service('plugin.manager.migrate.destination')->getDefinitions()));" + +# Plugin definitions for a destination plugin. Replace PLUGIN_ID with one of the values of the command above. +$ drush php:eval "print_r(\Drupal::service('plugin.manager.migrate.destination')->getDefinitions()['PLUGIN_ID']);" + +``` ## Source section definition