Contentful Migrations

This package customizes Contentful Migration to better assist with working with multiple environments and spaces

How do I get set up?

• Install: run npm i @trimble-creative-strategy/contentful-migration-mxp -g
• Run: enter migrations to start the CLI in the terminal.
• Alternately, pass parameters/flags to migrations. For example: migrations --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --environmentId feature-1 --contentType hero --deleteAssets --deleteContentTypes --parentEnvironmentId feature-2 --parentSpaceId dOlzACxDb --parentAccessToken U2%8kSxqm0lzQ*A4 --childEnvironmentIds "feature-3, feature-4, feature-5" --childSpaceId 456zACxDb --childAccessToken 1238kSxqm0lzQ*A4 --awsAccessKey ABC123 --awsSecretAccessKey DEF456 --s3BucketName your-bucket-name --s3BucketRegion us-east-1

Parameters

• --accessToken: String,
• --spaceId: String,
• --environmentId: String,
• --contentType: String,
• --assetsDirectory: String,
• --contentFile: String,
• --awsAccessKey: String,
• --awsSecretAccessKey: String,
• --s3BucketName: String,
• --s3BucketRegion: String,
• --deleteAssets: Boolean,
• --deleteContentTypes: Boolean,
• --parentEnvironmentId: String,
• --parentSpaceId: String,
• --parentAccessToken: String,
• --childEnvironmentIds: String,
• --childSpaceId: String,
• --childAccessToken: String,
• --importContent: Boolean,
• --importAllContent: Boolean,
• --contentTypes: String,
• --skipBackup: Boolean,
• --originEnvironment: String,
• --newEnvironment: String,

Functions

MasterBackupExport

This exports the entire Environment as well as assets. The export & assets are zipped and then stored in an s3 bucket

Parameters:

• accessToken - Contentful Management API token
• spaceId - Contentful Space
• environmentId - Contentful Environment to Backup. example: master-2021-09-01
• awsAccessKey - AWS IAM access key
• awsSecretAccessKey - AWS IAM secret access key
• s3BucketName - AWS s3 Bucket Name
• s3BucketRegion - AWS s3 Bucket region
• s3BucketDirectory - AWS s3 Bucket Directory. The Directory should be the space name. ie. corporate, geospatial etc

Example:

migrations MasterBackupExport --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --environmentId master-2021-09-01 --awsAccessKey AKAIPwTovbcKPttTxeHLxQJK --awsSecretAccessKey rLJihvPmmYnypNNttXYh --s3BucketName example-bucket-name --s3BucketRegion us-east-1

MasterBackupImport

This imports an entire local Environment as well as assets to a Contentful environment.

Parameters:

• accessToken - Contentful Management API token
• spaceId - Contentful Space
• environmentId - Contentful Environment to Backup. example: master-2021-09-01
• assetsDirectory - path to directory with assets folders
• contentFile - path to export.JSON file

Example:

migrations MasterBackupImport --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --environmentId master-2021-09-01 --assetsDirectory ./export --contentFile ./export/export.json

FeatureEnvExport

This exports a feature environment so it can then be imported with FeatureEnvImport.

It exports only the content types and the entries tagged with the required/do-not-delete tag.

Parameters:

• environmentId - Contentful Environmeto Backup. example: feature-1
• spaceId - Contentful Space
• accessToken - Contentful Management token

Example:

migrations FeatureEnvExport --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --environmentId feature-env

FeatureEnvImport

This uploads an exported feature environment to Contentful.

Parameters:

• environmentId - Contentful Environment to Backup. example: feature-1
• spaceId - Contentful Space
• accessToken - Contentful Management API token

Example:

migrations FeatureEnvImport --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --environmentId feature-env

DeleteAllEntriesOfType

This will delete all of the entries of a specific content. Necessary when exporting/importing a deleted content type.

Parameters:

• environmentId - Contentful Environment to Backup. example: feature-1
• spaceId - Contentful Space
• accessToken - Contentful Management API token
• contentType - Content type to delete entries of

Example:

migrations DeleteAllEntriesOfType --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --environmentId feature-env --contentType pullQuote

EnvironmentClean

This will delete all of the content entries in a specified environment.

Parameters:

• environmentId - Contentful Environment to Backup. example: feature-1
• spaceId - Contentful Space
• accessToken - Contentful Management API token
• deleteAssets - Also delete all assets in the environment (if true)
• deleteContentTypes - Also delete all content types in the environment (if true)

Example:

migrations EnvironmentClean --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --environmentId feature-env --deleteAssets --deleteContentTypes

ParentChildTrickleDown

This creates backups of each listed child environment and performs a FeatureEnvImport operation from the parent environment into each listed child environment.

Parameters:

• awsAccessKey - AWS IAM access key
• awsSecretAccessKey - AWS IAM secret access key
• s3BucketName - AWS s3 Bucket Name
• s3BucketRegion - AWS s3 Bucket region
• parentEnvironmentId: The parent environment ID,
• parentSpaceId: The parent space ID,
• parentAccessToken: The parent access token,
• childEnvironmentIds: The child environment ID,
• childSpaceId: The child space ID,
• childAccessToken: The child access token,

Example:

migrations ParentChildTrickleDown --awsAccessKey ABC123 --awsSecretAccessKey DEF456 --s3BucketName your-bucket-name --s3BucketRegion us-east-1 --parentEnvironmentId parent-environment --parentSpaceId 123456abc --parentAccessToken 789101def --childEnvironmentIds "child-1, child-2" --childSpaceId 654321def --childAccessToken 101987abc

ContentTypeTrickleDown

This creates backups of each listed child environment and migrates the content and models of each specified content type from the parent environment to all child environments.

Parameters:

• awsAccessKey - AWS IAM access key
• awsSecretAccessKey - AWS IAM secret access key
• s3BucketName - AWS s3 Bucket Name
• s3BucketRegion - AWS s3 Bucket region
• parentEnvironmentId: The parent environment ID,
• parentSpaceId: The parent space ID,
• parentAccessToken: The parent access token,
• childEnvironmentIds: The child environment ID,
• childSpaceId: The child space ID,
• childAccessToken: The child access token,
• importContent: If true, imports any specified model(s) content and assets tagged as "Required - do not Delete" into the child environments,
• importAllContent: If true, imports all content and assets belonging to the specified model(s) into the child environments,
• contentTypes: A coma delimetered list of content type ids to migrate for the parent to children,
• skipBackup: If true, skips the backup process of child spaces to s3,

Example:

migrations ContentTypeTrickleDown --awsAccessKey ABC123 --awsSecretAccessKey DEF456 --s3BucketName your-bucket-name --s3BucketRegion us-east-1 --parentEnvironmentId parent-environment --parentSpaceId 123456abc --parentAccessToken 789101def --childEnvironmentIds "child-1, child-2" --childSpaceId 654321def --childAccessToken 101987abc --importContent --importAllContent --contentTypes "content-type-1, content-type-2, content-type-3" --skipBackup

CreateNewEnvironment

This will create a new Environment from a previous Environment. This should be used rather than the Contentful Web App. This only migrates the content types and placeholder entries, providing a more accurate space to work in.

Parameters:

• spaceId - Contentful Space
• accessToken - Contentful Management API token
• newEnvironment - Contentful Environment to create. example: feature-1
• originEnvironment - Contentful Environment to clone from. (Will most likely be master). example: master

Example:

migrations CreateNewEnvironment --accessToken U2%8kSxqm0lzQ*A4 --spaceId dOlzACxDb --newEnvironment feature-1 --originEnvironment master

Developer Workflow

1. Create new environment with CreateNewEnvironment migration

   • Note: accessing your new environment:
     • Go into API Keys settings in Contentful and select the API key you are using
     • Scroll to the bottom and Click the checkbox next to your new environment
     • Error debug video

2. Do work!

   • Note: be careful when deleting fields in Contentful:

   • Use only Disable in response or Disable editing at first.

   • Delete later and run migrations or manually

3. Make sure to add tag requiredDoNotDelete to new Content Entries

4. Make sure references and assets have tag requiredDoNotDelete

5. Run FeatureEnvExport of <feature-branch> and FeatureEnvImport into qa-uat and dev

   • Note: If Deleting a Content Type, you will need to run deleteAllEntriesOfType on target environment before Import

6. Once qa has passed run FeatureEnvExport of qa-uat, and then FeatureEnvImport it into staging

7. Once Staging has been tested run FeatureEnvExport on staging

8. Create a new master<current-date> branch from the current master<date> branch

9. Run FeatureEnvImport into new master<current-date> branch

10. Switch ALIAS in Contentful from old master to new master

11. When all is good, run MasterBackupExport on old master<date> branch

12. Old master<date> branch can be deleted