Here is everything you need to know when using the Import/Export feature to duplicate a repository. This is often done to sync dev/staging/prod repositories.

 

General Issues

The first thing we need to cover are some of the general limitations of exporting from one repository and importing into another.

  • You can't import media items (except for Images into an Image field). This will need to be done manually after the import has been done.
  • Content Relationships aren't maintained. Any Content Relationship or link to another Prismic document will need to be re-added after the import has been done.
  • There is not currently support for importing Integration Fields. Any Integration Field content will need to be re-selected manually after the import has been done.
  • Releases aren't synced. Releases aren't a part of the Import/Export process. So any release you want in the Import repository will need to be manually re-created after the import.
  • There is no way to clone or duplicate Custom Types between the repos with the Import feature. You will need to copy and paste the Custom Type JSON manually between the two repositories.
  • You will lose Image positioning and zoom in the Export/Import process.
  • Documents do not retain their History information. When a document is imported from another repository, it will appear as a new document without any prior history. You will no longer be able to roll back to a previous version of the document.
  • You will not migrate any unpublished documents unless you follow the instructions below.
  • You will not migrate any archived documents unless you follow the instructions below.

 

How to migrate an unpublished Document

  1. Before doing the export of your repository below, publish the document. This will ensure that it is part of the Export/Import.
  2. Do the import as explained below....
  3. After you have imported your documents into your other repo, archive the document.
  4. Go to the Archived tab and click on the document.
  5. Click on the history button for the document.
  6. Restore the previous version.
  7. This will take it back to being an unpublished draft in your Working tab.

 

How to migrate an Archived Document

  1. Before doing the export of your repository below, publish the document. This will ensure that it is part of the Export/Import.
  2. Do the import as explained below....
  3. After you have imported your documents into your other repo, re-archive the document.

 

Importing into an empty repository

When exporting from one repository and importing into an empty repo, the process is a little different depending on if you have more than one language in your repository.

Keep in mind that all of the limitations outlined in the General Issues section above apply to this process.
 

Multi-Language Import

Here are the steps to take if you have more than one language in your repositories:

  1. Start by copy and pasting all your Custom Types from the first repository to the second. There is no way to automate this, unfortunately, so you will need to copy the JSON code for each Type and recreate it in the other repository. Make sure that the API ID of the types exactly match those of the export repository.
  2. Follow the instruction above to include any unpublished or archived documents that you want to migrate.
  3. Go to the first repository's Settings > Import/Export.
  4. Click the "Export your documents".
  5. Download the export.

Then prepare the export files for import. You need to modify the exported JSON files as if you were importing them for the first time.

  1. Modify the file names to match the correct format for importing new documents and translations as shown here: https://user-guides.prismic.io/import/import-for-multiple-languages
  2. For each document in a translation group give it a name like the following. In order for the documents to be associated correctly, they need to match except for the language code: new_document001_en-us.json, new_document001_fr-fr.json 
  3. You need to make sure that all the language versions of a translation group get imported together. This is only a concern if you are importing more than 200 documents and need to import them in batches.
  4. For each translation group you need to make sure that the document001  part of the file name is unique from all the other translation groups.
  5. You don't need to modify anything in the json code, just the filenames.
  6. Once you've renamed all the json files, select them all and compress them directly. Don't compress the folder they are in, the import won't work if you do this. You need to directly select all the files, and compress them that way.
  7. Feel free to share your zip file with the Prismic support team to verify that you have correctly renamed the files.

 Here are the final Import steps:

  1. Go to the second repository's Settings > Translations & Locals and add all the same languages as you have in the first repo.
  2. Go to the Settings > Import/Export.
  3. Import your content. You might see the following warning appear if you have any links to other Documents / Content Relationships. You can ignore warnings such as this: Unable to find document W6ThVycAACcA1jDT 
  4. For any Image you might also get a warning which you can ignore: Unable to find media V8fjgCoAACkAesTn 
  5. If you see any other errors, ask the Prismic support team for help with them.
  6. Once you've completed the import, the documents will appear in a release. All you need to do is publish this release and your content will be live.
  7. Make sure to re-add anything lost in the Export/Import process: Document Links / Content Relationships, Links to Media Items, Integration Fields selections, Image zooming & cropping.
  8. Make sure to follow the steps shown above to re-archive your archived documents and reset your unpublished ones.
  9. Update the repository's settings (Previews, Collections, etc.) to match the original's settings.

 

Single Language Import

It is a little easier to Import into an empty repository when there is only one language to deal with. Here are the steps:

  1. Start by copy and pasting all your Custom Types from the first repository to the second. There is no way to automate this, unfortunately, so you will need to copy the JSON code for each Type and recreate it in the other repository.
  2. Follow the instruction above to include any unpublished or archived documents that you want to migrate.
  3. Go to your repository's Settings > Import/Export.
  4. Click to "Export your documents".
  5. Download the export.
  6. If the export has more than 200 files, then you will need to break this down into separate Import files. There is a limit of 200 documents per import, so you will need to separate the import into batches of up 200 documents.
  7. If you have to separate your files, select the batch of files and compress them directly. Don't compress the folder they are in, the import won't work if you do this. You need to directly select all the files, and compress them that way.
  8. Go to the Settings > Import/Export in your other repository.
  9. Import your content. You might see the following warning appear if you have any links to other Documents / Content Relationships. You can ignore warnings such as this: Unable to find document W6ThVycAACcA1jDT 
  10. For any Image you might also get a warning which you can ignore: Unable to find media V8fjgCoAACkAesTn 
  11. If you see any other errors, ask the Prismic support team for help with them.
  12. Once you've completed the import, the documents will appear in a release. All you need to do is publish this release and your content will be live.
  13. Make sure to re-add anything lost in the Export/Import process: Document Links / Content Relationships, Links to Media Items, Integration Fields selections, Image zooming & cropping.
  14. Make sure to follow the steps shown above to re-archive your archived documents and reset your unpublished ones.
  15. Update the repository's settings (Previews, Collections, etc.) to match the original's settings.

 

Importing into an non-empty repository

When exporting from one repository and importing into a non-empty repo, the process is a little more complicated.

Keep in mind that all of the limitations outlined in the General Issues section apply to this process.

The easiest way to import into a non-empty repository to sync your two repositories is to completely clear out the import repository before running the Import.

  1. Completely delete all the documents in the repository. Here is an article explaining how to do this: https://intercom.help/prismicio/browse-documents-and-edit-content/editing-content/archive-or-delete-a-document-from-your-repository. Unfortunately there is no way to bulk delete documents, you will need to delete them all one-at-a-time.
  2. Completely delete all the media assets in the repository. Even if a particular media asset exists, if you import it from another repo, it will create a new copy of the asset leading to duplicates in your media library. If you don't want to have duplicates, then you should delete all your media before running the import. Unfortunately there is no way to bulk delete your media assets. You will need to delete them all one-at-a-time.
  3. Update all the Custom Types so that they perfectly match the Custom Types of the repository you are exporting from.

Once you've cleared everything out, you can follow the instructions above as if you were importing into an empty repository.

Did this answer your question?