Environment support for References across spaces

Table of contents

• How to copy an environment containing cross-space links
• How to repoint a master alias to another environment: aliased environments
• How to repoint a master alias to another environment: aliased environments
• How to delete an environment
• How to merge two environments
• How to add a master alias in an existing setup with references
• How to import entries and content types

Environments with References across spaces

You can use references across spaces to point to non-master environments and carry out testing and staging changes across spaces in the content development workflow. This page contains a few use cases of the extended environment support to show you how you can use the feature in your content development.

For all of the example scenarios, we assume the user has:

• three spaces linked together using cross-space links
• access to all of these spaces
• permissions to create new environments
• properly set up the contentful CLI and the Merge app CLI
• already selected the main space to work on via the contentful space use.

How to copy an environment containing cross-space links

Consider the following scenario:

• You have three spaces, Space A, Space B and Space C that are linked together using cross-space links, with Space A being the main space.
• The cross-space links are linked between the master environments of these three spaces.

When copying the master environment of Space A, it is copied as a new environment called, in this case, master-new, as pictured below:

The cross-space links in the master-new environment are the exact same copy of the source environment (master), meaning they all point to other master environments. This setup works, because the new environment has the identical content types, entries and references. However, if you want to have a mirrored setup, meaning have a copied environment point to another copied environment (as pictured below), you must take some additional steps.

Workflow

Follow these steps to have your copied environment point to another copied environment:

1. In the contentful CLI, use the following command to create a copy of the master environment in Space A: contentful space environment create --source master --environment-id 'master-new' --name 'master-new'. The copy environment is called master-new.

2. Switch to Space B using the following command: contentful space use spaceB.

3. Copy the master environment in Space B: contentful space environment create --source master --environment-id 'master-new' --name 'master-new'.

4. Switch to Space C using the following command: contentful space use spaceC.

5. Copy the master environment in Space C: contentful space environment create --source master --environment-id 'master-new' --name 'master-new'.

6. Update the references between the linked environments.
   

   How to repoint a master alias to another environment: aliased environments

   Consider the following scenario:

• You have three spaces, Space A, Space B and Space C that are linked together using cross-space links, with Space A being the main space.
• Every space has two environments, one of them being aliased as master.
• The cross-space links are linked between the master aliases of these three spaces.

Workflow

To have the master alias of the main space, Space A, point to another environment along with all the linked references to also reference master aliases from other spaces, follow these steps:

1. In the contentful CLI, use the following command to repoint the master alias environment in Space A to the new environment: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

2. Switch to Space B using the following command: contentful space use spaceB.

3. Update the alias for master to point to the desired environment in Space B: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

4. Switch to Space C using the following command: contentful space use spaceC.

5. Update the alias for master to point to the desired environment in Space C: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

6. Switch to Space B again and update the reference to point to the aliased master environment.

7. Switch to Space C and update the reference to point to the aliased master environment.

How to repoint a master alias to another environment: non-aliased environments

Consider the following scenario:

• You have three spaces, Space A, Space B and Space C that are linked together using cross-space links, with Space A being the main space.
• Every space has two environments, one of them being a non-aliased master.
• The cross-space links are linked between the master environments of these three spaces.

To have the master alias of the main space, Space A, point to another environment along with all the linked references to also reference master environments from other spaces, follow these steps:

1. In the contentful CLI, use the following command to repoint the master alias in Space A to the new environment: contentful space environment-alias update --alias-id 'master' --target-environment-id 'master-08'.

2. Switch to Space B using the following command: contentful space use spaceB.

3. Merge changes from the new environment into master for Space B.

4. Switch to Space C using the following command: contentful space use spaceC.

5. Merge changes from the new environment into master for Space C.

6. Update the references in the main space to point to master environment of Space B.

How to delete an environment

Consider the following scenario:

• You have two spaces, Space A and Space B that are linked together using cross-space links, with Space A being the main space.
• The main space, Space A has two environments.

Workflow

To delete one environment in Space A, use the following command in the contentful CLI: contentful space environment delete --environment-id <environment-id>

NOTES:

• You must first investigate what references are pointing to the environment you want to delete. You can do so by running the contentful export space command and investigating the generated JSON file. If such references exist, they should be pointed to other resources, otherwise the links will not be resolvable.
• You cannot delete non-aliased master or environments aliased as master.

How to merge two environments

Consider the following scenario:

• You have two spaces, Space A and Space B that are linked together using cross-space links, with Space A being the main space.
• The main space, Space A has two environments which have diverged.

Workflow

1. Generate the script using this command: contentful merge export --source-environment-id master-new --target-environment-id master.
2. Run the migration script: contentful space migration --space-id <my-space-id> migration-file.js.

How to add a master alias in an existing setup with references

Consider the following scenario:

• You have at least two spaces, Space A, Space B, that are linked together using cross-space links, with Space A being the main space.
• The space being referenced from the main space has two environments, one of them being a non-aliased master.
• The cross-space links are linked between master environments of these two spaces.

If you want to introduce a master alias to a space with previously non-aliased master environment that was being referenced from other spaces, we recommend you review any changes made to the master alias, as it can led to having the main space referencing non obvious content (initially it was referencing explicit master environment of Space B, but alias can be repointed).

The alias gets repointed to a different environment, and behind the scenes, Space A starts referencing different content.

How to import entries and content types

You can use additional tools to export and import content between spaces. For example, you can use the contentful space export CLI command or the contentful-export package directly. We recommend you review any diffs or files generated by those tools for the occurrences of cross-space links. The environments used in those links should be updated before being used as a source of truth for importing.