From 017f761e3ebc6637a9d57020aa7432de8672c5e4 Mon Sep 17 00:00:00 2001 From: Steve Wirt Date: Fri, 27 Oct 2023 17:37:32 -0400 Subject: [PATCH] VACMS-15893 Add setup for CM Document export/import. --- .../content_model_documentation.settings.yml | 1 + .../va_gov_migrate/cm_documents/README.md | 7 +++ ...szZz125zZzimporting-site-documentation.yml | 63 +++++++++++++++++++ .../va_gov_migrate/va_gov_migrate.install | 24 +++++++ 4 files changed, 95 insertions(+) create mode 100644 docroot/modules/custom/va_gov_migrate/cm_documents/README.md create mode 100644 docroot/modules/custom/va_gov_migrate/cm_documents/adminzZzstructurezZzcm-documentzZzprocesszZz125zZzimporting-site-documentation.yml diff --git a/config/sync/content_model_documentation.settings.yml b/config/sync/content_model_documentation.settings.yml index 7fd4d83b459..ca559ab13f9 100644 --- a/config/sync/content_model_documentation.settings.yml +++ b/config/sync/content_model_documentation.settings.yml @@ -6,3 +6,4 @@ node: 1 paragraph: 1 taxonomy: 1 modules: 1 +export_location: va_gov_migrate diff --git a/docroot/modules/custom/va_gov_migrate/cm_documents/README.md b/docroot/modules/custom/va_gov_migrate/cm_documents/README.md new file mode 100644 index 00000000000..643f8bcffce --- /dev/null +++ b/docroot/modules/custom/va_gov_migrate/cm_documents/README.md @@ -0,0 +1,7 @@ +# Export directory for Content Model Documentation document exports + +This directory is the temporary storage for CM Documents exported locally and +then imported to Prod. Once they have been imported on prod, they are safe to +be deleted from here. + +We should be "safe" removing anything that is more than 2 weeks old (to cover thngs like Holiday code freezes). diff --git a/docroot/modules/custom/va_gov_migrate/cm_documents/adminzZzstructurezZzcm-documentzZzprocesszZz125zZzimporting-site-documentation.yml b/docroot/modules/custom/va_gov_migrate/cm_documents/adminzZzstructurezZzcm-documentzZzprocesszZz125zZzimporting-site-documentation.yml new file mode 100644 index 00000000000..079f0ebc3c0 --- /dev/null +++ b/docroot/modules/custom/va_gov_migrate/cm_documents/adminzZzstructurezZzcm-documentzZzprocesszZz125zZzimporting-site-documentation.yml @@ -0,0 +1,63 @@ +uuid: 1b66dd91-8f61-45ec-9d4a-df64c3761a4b +langcode: en +type: cm_document +bundle: cm_document +id: '125' +dependencies: + config: + - cm_document.cm_document_type.cm_document + - field.field.cm_document.cm_document.field_data_pulled_from + - field.field.cm_document.cm_document.field_data_pushed_to + - field.field.cm_document.cm_document.field_diagram + - field.field.cm_document.cm_document.field_links_to_design + - field.field.cm_document.cm_document.field_links_to_research + - field.field.cm_document.cm_document.field_link_to_cms_design_system + - field.field.cm_document.cm_document.field_link_to_va_design_system + - field.field.cm_document.cm_document.field_other_links + - field.field.cm_document.cm_document.field_related_knowledgebase + - field.field.cm_document.cm_document.field_screenshots + - field.field.cm_document.cm_document.field_stakeholders + entity: + - 'user:user:efa9900b-7446-41bf-b6a9-a99287ae2235' +fields: + vid: '183' + revision_created: '1698441703' + revision_user: + target_id: '1215' + _entity: 'user:user:efa9900b-7446-41bf-b6a9-a99287ae2235' + revision_log_message: 'Adding diagram.' + status: '1' + user_id: + target_id: '1215' + _entity: 'user:user:efa9900b-7446-41bf-b6a9-a99287ae2235' + name: 'Importing site documentation' + documented_entity: site.process + notes: + value: "

Exporting

\r\n\r\n

Exporting content model documents can be done using Drush to export them as yml files.
\r\nThe key to exports is the entity id.

\r\n\r\n
    \r\n\t
  1. Visit the config page for the module and set the machine name for the local
    \r\n\tcustom module that you want to contain the yml files for any exported CM Documents.
    2. \r\n\t
  2. Create or edit a CM Document. Save your work
    3. \r\n\t
  3. Hover over the \"edit\" tab to reveal the id of the CM Document.
    4. \r\n\t
  4. In your terminal type drush content-model-documentation:export <id>
    \r\n\tA yml file was just created in your local module. at <local>/cm_documents/<page>.yml
    5. \r\n\t
  5. Commit this export file like any other. (repeat steps as needed)
    6. \r\n
\r\n\r\n

Importing

\r\n\r\n

The key to importing is the alias of the exported page.

\r\n\r\n

Import using hook_update_n()

\r\n\r\n
    \r\n\t
  1. In your local module (usually the same one that is used for saving the exports)
    \r\n\tadd or open the .install file.
    2. \r\n\t
  2. Gather the aliases from the pages you want to import (not including the domain).
    3. \r\n\t
  3. Add the something similar to this to the .install file.
    4. \r\n
\r\n\r\n
\r\n

/**
\r\n  * Import some CM Documents.
\r\n  */
\r\nfunction va_gov_migrate_update_9017() {
\r\n  $cm_documents_to_import = [     '/admin/structure/types/manage/promo_banner/document',      '/admin/structure/types/manage/full_width_banner_alert/document',
\r\n];

\r\n\r\n

// Use TRUE if it is a new CM Document.
\r\n// Use FALSE if its an update to an existing CM Document
\r\n$strict = TRUE;
\r\nreturn CmDocumentImport::import($cm_documents_to_import, $strict);
\r\n}

\r\n
\r\n\r\n

The $strict determines whether the update is considered a failure if any of the
\r\nCM Documents do not import. TRUE will cause the hook_update to consider a failure if any of the imports get rejected. FALSE will allow the rejections to happen but still
\r\nconsider the update a success.

\r\n\r\n
    \r\n\t
  1. WHen drush updb is run, the content will create new entities or update existing.
    2. \r\n
\r\n\r\n

What causes an import to get rejected?

\r\n\r\n\r\n\r\n

Import using Drush

\r\n\r\n

If you did not want to use a hook_update_n() to deploy your changes, you can use Drush.

\r\n\r\n
    \r\n\t
  1. Find the alias of the CM Document that you want to import.
    2. \r\n\t
  2. Use the alias in the command drush content-model-documentation:import '/alias/of/the/cm-document'
    3. \r\n
\r\n" + format: rich_text + created: '1698441103' + changed: '1698441703' + revision_translation_affected: { } + revision_default: '1' + metatag: { } + field_data_pulled_from: { } + field_data_pushed_to: { } + field_diagram: + - + title: 'Workflow for deploying documentation' + diagram: "flowchart TD\r\n A[Add your code] --> B[Write your CM Document locally]\r\n B --> C[Grab the ID of the document]\r\n C -->D[Use ID in Drush export command]\r\n D -->E[Copy the alias]\r\n E -->F[Add hook_update_n to va_gov_migrate using the alias]\r\n F -->G[Commit your code]" + caption: "The workflow is: \r\nAdd your code. Write your CM Document locally. Grab the ID of the document. Use ID in Drush export command. Copy the alias. Add hook_update_n to va_gov_migrate using the alias. Commit your code." + key: '' + show_code: '1' + field_links_to_design: { } + field_links_to_research: { } + field_link_to_cms_design_system: { } + field_link_to_va_design_system: { } + field_other_links: + - + uri: 'https://www.drupal.org/project/content_model_documentation' + title: 'Content Model Documentation module project page (same as README in the module)' + options: { } + field_related_knowledgebase: { } + field_screenshots: { } + field_stakeholders: { } diff --git a/docroot/modules/custom/va_gov_migrate/va_gov_migrate.install b/docroot/modules/custom/va_gov_migrate/va_gov_migrate.install index f2cc53e471d..48ca62cbb88 100644 --- a/docroot/modules/custom/va_gov_migrate/va_gov_migrate.install +++ b/docroot/modules/custom/va_gov_migrate/va_gov_migrate.install @@ -5,6 +5,7 @@ * Update functions for the va_gov_migrate module. */ +use Drupal\content_model_documentation\CmDocumentMover\CmDocumentImport; use Drupal\Core\Database\Database; use Drupal\Core\File\FileSystemInterface; use Drupal\Core\StreamWrapper\PublicStream; @@ -201,3 +202,26 @@ function va_gov_migrate_update_8010() { return $messages; } + +/** + * Update Content Model Documentation ahead of congi import. + */ +function va_gov_migrate_update_9001() { + $config_factory = \Drupal::configFactory(); + $config = $config_factory->getEditable('content_model_documentation.configuration'); + $config->set('export_location', 'va_gov_migrate'); + $config->save(TRUE); + return 'Added storage location for Content Model Documentation module.'; +} + +/** + * Import documentation about Importing documentation. + */ +function va_gov_migrate_update_9002() { + $cm_documents_to_import = [ + '/admin/structure/cm_document/process/125/importing-site-documentation', + ]; + // Consider using TRUE for new CM Documents, and FALSE for updating existing. + $strict = TRUE; + return CmDocumentImport::import($cm_documents_to_import, $strict); +}