Updating Cross-space references using the Contentful CLI

There are two ways users can review which spaces and environments are using cross-space links and which links should be updated:

1. Exporting contents of every space using contentful-export and contentful-import.
2. Creating custom migration scripts.

1. Export contents of a space

When exporting the contents of a space, follow these steps:

1. Export contents of a single space using the following command: contentful space export. The resulting .json file contains all the information about the space. The important properties are the contentTypes and entries.

{
  "contentTypes": [
    {
      "sys": {
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "space-a-id"
          }
        },
        "id": "restaurant",
        "type": "ContentType"
      },
      "displayField": "name",
      "name": "Restaurant",
      "description": "",
      "fields": [
        {
          "id": "name",
          "name": "Name",
          "type": "Symbol"
        },
        {
          "id": "menu",
          "name": "Menu",
          "type": "Array",
          "items": {
            "type": "ResourceLink",
            "validations": []
          },
          "allowedResources": [
            {
              "type": "Contentful:Entry",
              "source": "crn:contentful:::content:spaces/space-b-id/environments/master",
              "contentTypes": ["dish"]
            }
          ]
        },
        {
          "id": "about",
          "name": "About",
          "type": "RichText",
          "validations": [
            {
              "enabledMarks": [],
              "message": "Marks are not allowed"
            },
            {
              "enabledNodeTypes": ["embedded-resource-block"],
              "message": "Only block entry from a different space nodes are allowed"
            },
            {
              "nodes": {
                "embedded-resource-block": {
                  "validations": [],
                  "allowedResources": [
                    {
                      "type": "Contentful:Entry",
                      "source": "crn:contentful:::content:spaces/space-b-id/environments/master",
                      "contentTypes": ["address"]
                    }
                  ]
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "entries": [
    {
      "sys": {
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "space-a-id"
          }
        },
        "id": "5gDrXf0Nf223qHTWNnxNwn",
        "type": "Entry",
        "environment": {
          "sys": {
            "id": "master",
            "type": "Link",
            "linkType": "Environment"
          }
        },
        "contentType": {
          "sys": {
            "type": "Link",
            "linkType": "ContentType",
            "id": "restaurant"
          }
        }
      },
      "fields": {
        "name": {
          "en-US": "My favorite pizza place"
        },
        "menu": {
          "en-US": [
            {
              "sys": {
                "type": "ResourceLink",
                "linkType": "Contentful:Entry",
                "urn": "crn:contentful:::content:spaces/space-b-id/environments/master/entries/dish-1-id"
              }
            },
            {
              "sys": {
                "type": "ResourceLink",
                "linkType": "Contentful:Entry",
                "urn": "crn:contentful:::content:spaces/space-b-id/environments/master/entries/dish-2-id"
              }
            }
          ]
        },
        "about": {
          "en-US": {
            "content": [
              {
                "content": [
                  {
                    "value": "This is my favorite pizza restaurant!",
                    "nodeType": "text"
                  }
                ],
                "nodeType": "paragraph"
              },
              {
                "data": {
                  "target": {
                    "sys": {
                      "urn": "crn:contentful:::content:spaces/space-b-id/environments/master/entries/4vxXfphlVtXmbyvMsnL4U9",
                      "type": "ResourceLink",
                      "linkType": "Contentful:Entry"
                    }
                  }
                },
                "nodeType": "embedded-resource-block"
              }
            ],
            "nodeType": "document"
          }
        }
      }
    }
  ]
}

2. Analyze the members of the contentTypes array and their .fields property. Identify all fields that contain array allowedResources. Be aware it can be both fields of type ResourceLink, as well as RichText.

3. For each element of collected allowedResources, inspect its source property containing the definition of allowed cross-space links. Investigate which of these are relevant to your use case and update their evironments segment accordingly.

If the link does not contain the environment segment, it means it is implicitly pointing to a master environment. You can still add the explicit segment following this format: crn:contentful:::content:spaces/<space-id>/environments/<environment-id>.

4. Analyze the members of entries array and their .fields property. Identify all fields that contain urn property and are of content type that you have adjusted in previous steps. Update the urn accordingly, by adding the environments segment.

5. Once you are done with editing, you can import changed json file and apply changes to the space: contentful space import –content-file name-of-json-file.json.

6. Repeat all these steps for all linked spaces.

IMPORTANT: This approach recreates the modified entries (possibly losing versioning / history?). For more information, see Importing to a space with existing content.

2. Create a custom migration script

The Merge CLI allows users to run migrations, which can be a combination of scripts generated by CLI and modifications implemented by the users. By running the command contentful merge export --te <source-environment> --se <target-environment>, users can generate a base migration script editing the content model. This base migration script can be further enhanced to apply necessary changes, as well to add transformations for entries. For more information about this, see:

• documentation on transformEntries() method
• example usage

In addition, you can use the Content Management API to update content models and update entries.