Implementation Guide

Since the task at hand is creating entities and we're already working with migrations, the approach shown here is to use migrations to generate the QA related entities. Also, the approach shown here is intended to be simple and clear. There are certainly ways to set this up that perform better, so consider this a starting point, then extend and refine. There may appear to be some redundant work here, between trackers, connectors, and migrated content, but this structure allows flexibility for workflows that are more unique than this simpler starter.

File locations and names

The general recommendation is to keep QA migrations in their own module. This is to maintain a distinction between content and QA migrations. But there's nothing wrong with keeping QA migrations in the same module as content migrations either. It's a matter of how you like to be organized.

It's highly recommended to use groups, enabled by the migrate_plus module. Individual migration names can be prefixed with the group names. Example qa_tracker group, with qa_tracker_node_article and qa_tracker_media_document migrations.

Tracker migrations

First, decide which regular migrations you want to track. Migrations that create nodes are the most likely. Other migrations to consider tracking are Users, Media, and Blocks. If you have a Files migration that a Media migration depends on, you probably don't need to track them both; tracking the media migration will be enough. Similarly, if you have a Paragraphs migration that a Node migration depends on, you probably don't need to track them both, since the paragraphs will be visible on nodes. But if you do want to have a stage of reviewing paragraphs on their own, before nodes come in, you can do that too.

Use the same migration source as the content migration that it's tracking.

Suggested name pattern: qa_tracker_[content-migration-name]

Example name: qa_tracker_node_article

The destination is plugin: 'entity:migrate_qa_tracker'.

Important process mappings are original_id and original_url. They're used mainly for display purposes and help reiterate which content they relate to.

Run after content has been imported. Do not roll back once data is in trackers.

Connector migrations

Use the same migration source that the tracker and content migrations are using.

Suggested name pattern: qa_connector_[entity-type] or qa_connector_[content-migration-GROUP-name].

Example name: qa_connector_node

The destination is plugin: 'entity:migrate_qa_connector'

Process mappings:

• tracker: use a migration_lookup based on the tracker migration.
• content/target_id: use a migration_lookup based on the content migration.
• content/target_type: set it to the base entity type of the imported content, e.g. node or media.

This must be run only after the content migrations has been run. Running connector migrations before tracker migrations will generate trackers using migrate's stub generation process. When content migrations are rolled back and reimported, do the same with their connector migrations, rolling them back and reimporting.

Flag migrations

Use the same migration source as the other migrations.

Suggested name pattern: qa_flag_[content-migration-name]_[field-inspected]_[flag-name]

Example name: qa_flag_body_iframe

The destination is plugin: 'entity:migrate_qa_flag'.

Process mappings:

• tracker: use a migration_lookup based on the tracker migration.
• original_id and original_url: Use data from the source.
• field: text name of the field being examined. e.g. "body" or "field_body" or "description".
• flag_type: human readable name of this type of flag. e.g. "scripts" or "internal links".
• details: chain of several plugins: preg_match_all which takes a regex of what to look for and returns an array of matches, skip_on_empty so that no flag is created if nothing flaggable is found, formatted_text_prepare to create an array of value/format pairs, and finally a sub_process to map the result array to the target field.

Run these after content, tracker, and connector imports.

Views configuration

• Examples are in the migrate_qa_views and migrate_qa_views_media modules.
• Use Trackers as the base table for the view. This lets you have a persistent view of trackers, regardless of the state of imported content.
• Use views relationships to connect through the Connector entity to the imported Content. The relationship from Tracker to Connector is "Migrate QA Connector using tracker" in the Migrate QA Tracker category. The relationship from Connector to Content is the "Content to Media entities" or "Content to Content entities" etc. in the Migrate QA Connector category.
• Create a separate view or display for each entity type being imported. This is because the relationship from connector to imported content has to be for a specific entity type.
• Use the contrib module views_bulk_edit to enable applying an update to many trackers at once.
• Use the contrib module views_entity_form_field to turn the view into something a little more like a spreadsheet, updating values for each item in the list, and saving them all at once.