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
-
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
-
Note: accessing your new environment:
-
Do work!
-
Note: be careful when deleting fields in Contentful:
-
Use only
Disable in response
orDisable editing
at first. -
Delete later and run migrations or manually
-
-
Make sure to add tag
requiredDoNotDelete
to new Content Entries -
Make sure references and assets have tag
requiredDoNotDelete
-
Run
FeatureEnvExport
of<feature-branch>
andFeatureEnvImport
intoqa-uat
anddev
-
Note: If Deleting a Content Type, you will need to run
deleteAllEntriesOfType
on target environment before Import
-
Note: If Deleting a Content Type, you will need to run
-
Once qa has passed run
FeatureEnvExport
ofqa-uat
, and thenFeatureEnvImport
it intostaging
-
Once Staging has been tested run
FeatureEnvExport
onstaging
-
Create a new
master<current-date>
branch from the currentmaster<date>
branch -
Run
FeatureEnvImport
into newmaster<current-date>
branch -
Switch ALIAS in Contentful from old master to new master
-
When all is good, run
MasterBackupExport
on oldmaster<date>
branch -
Old
master<date>
branch can be deleted