1. Importing and exporting packages

Recover a failed import

If an import fails, entities with dependencies (for example, Portal.PageComponent and Portal.PageDefinition) are automatically rolled back to their previous state. Other changes from the import are not automatically reverted. To undo those changes, restore your environment using a recovery package.

You can use the recovery package generated during the failed import to restore your environment using the Sitecore Content Hub CLI or you can download the recovery package using the Entities API.

Recover a failed import using the CLI

To recover a failed import using the CLI:

  1. Find the job ID using one of the following methods:

    • In the UI, find the job ID either on the Recent processes page or the Background processes page.

    • In the CLI, run the following command:

      ch-cli jobs list -f Import

  2. Get the backup order ID for the failed import:

    ch-cli jobs report --id <IMPORT_JOB_ID>

  3. Download the recovery package for that backup order:

    ch-cli orders fetch --id <BACKUP_ORDER_ID>

  4. Restore the tenant using the recovery package:

    ch-cli system import -s "<URL_FROM_FETCH_OR_LOCAL_PATH_TO_PACKAGE>"

  5. Verify that the recovery process has completed successfully:

    ch-cli jobs status --id <JOB_ID>

Recover a failed import using the Entities API

To recover a failed import using the Entities API:

  1. In Sitecore Content Hub, go to the Background processes page and find the failed job import.

  2. Next to the failed job import, click View report, and copy the backup_order_id.

  3. Use the Entities API to retrieve the recovery package with the backup_order_id.

  4. In the returned JSON payload, scroll to the renditions section and locate the downloadOrder.

     "renditions": { 
    "downloadOrder": [
      {
        "href": "https://<CONTENT_HUB_INSTANCE>/api/delivery/<BACKUP_FILE_KEY>?intent=Download&expires..." 
      }
    ]
}

  5. Copy the URL from the href attribute and paste it into your browser to download the backup package .zip file.

  6. Import the package into your environment.

Best practices

Follow these best practices to ensure a safe and successful recovery:

  • Review error messages in the simulation summary report before proceeding.
  • Always use the correct CLI context and ensure you have the necessary permissions.
  • Do not skip steps—restoring from an incorrect package or skipping the recovery import can worsen tenant issues.
  • Monitor the import job until it completes to ensure successful recovery.
If you have suggestions for improving this article, let us know!