Entity Structure

The main thing this module does is provide an entity structure that lives distinct from any migrated content, so that it can be added at any point during a migration project, and can be removed completely without risk of interfering with migrated content.

This is also designed to support an iterative approach to migration development. Rollback and reimport all you want, without losing notes in trackers.

Trackers and Connectors are essential. Flags and Issues are available, but can be ignored if not needed.

All four entity types are fieldable, so if the default fields do not meet your needs, you can add fields and rearrange the existing fields.

Trackers

Trackers are the workhorse entity of the system. There is exactly one tracker for each piece of migrated content. These persist across multiple migrations and rollbacks. There are some permanent fields, such as Original ID and Original URL, some optional fields, such as Status and Tags. The field UI can be used to add custom fields.

Do not roll back migrations of trackers that people have entered real data into. This is the only migration that should not be rolled back, because these are what hold the notes and status that need to persist between migration runs.

Details:

• Created programmatically, by migrations
• One per migrated content
• Not to be rolled back once QA begins
• Editable
• Revisionable

Fields:

• Status - Select list
• Notes - Text field
• Tracker tags - Term References
• Tracker type - Term Reference
• Is Key Content - Checkbox
• Issues - Entity Reference

Connectors

This is what makes it possible to completely roll back and reimport migrations. Connectors exist only to connect trackers to the content they track. They have entity reference fields to point to a tracker and a piece of migrated content. These are distinct from trackers, instead of just being a field on trackers, to be maximally flexible.

• It makes it easy to reimport content and maintain its relationship with trackers, without the complication and potential errors of updating the trackers themselves.
• It supports a migration development process where destination entity types are shifting. For example, an early migration might bring something in as a node, and that gets noted as a bug in the tracker because it should actually be a media entity. The content migration can be rerun and the existing tracker will be linked to the media item via a recreated connector.
• Another use case is that some trackers may be used for listing content that is hoped to be migrated, but may not actually make it. Listing trackers with no connector is a way to answer the question "did we get all of the content we expected?".

Details:

• Created programmatically (by migrations)
• One per migrated content
• Rolled back with content migrations
• Not intended to be edited

Fields:

• Migrated Content - Dynamic Entity Reference
• Tracker - Entity Reference

Flags

Flags represent potential problems in migrated content, and are generated programmatically. (They're not related at all to the flag module.) For example, it can look at the body field and flag whether it has iframes, scripts, images, or internal links. For building views, there is a flag type filter (to see all content that has a certain flag type, such as iframes) and a flag summary field (to see all flags related to a piece of content).

Details:

• Created programmatically (by migrations)
• Can be multiple per migrated content
• Rolled back with content migrations
• Not intended to be edited manually

Fields:

• Original ID - String - Informational only
• Original URL - String - Informational only
• Field - String - To indicate which field the flag refers to
• Type - Term Reference - examples: iframe, scripts, internal links
• Details - Long text, multiple - For storing the entire string instance of what was flagged. Examples: the entire iframe code, the entire script, the img tag, etc. It's multiple value to store one value per instance, so if 3 iframes were found on one body field, their contents would be copied to 3 values in this field.
• Tracker - Entity Reference - The tracker corresponding to the migrated content.

Issues

Issues are for tracking problems that affect multiple pieces of content. They're similar to Tracker tags, except they're a dedicated entity type, with a known structure. They enable creating views that list all issues, and listing all content related to a given issue.

Details:

• Created manually, on trackers
• Can be multiple per migrated content
• Revisionable

Fields:

• Summary - String - Also serves as the label. Examples: Broken images, Scaled images, Wrong images.
• Description - Long Text - All the details about the issue
• Status - Select - Examples: Open, Resolved, etc.
• Field - String - The field the issue is seen in
• Tags - Term Reference - Examples: Images, Text