The Prismic import module is available with the Professional plans (starting at Medium). If you can't see the Import section under the Settings menu of the web app, you can reach out to the support team.
The number of documents you can import per batch is limited to 200 documents. And there is a limit of 10 import batches per hour. If you are running massive imports we recommend to keep each import size under 100 documents.
The Import/Export module lets you export, create new documents or update existing ones directly from your content repository's UI.
The module takes ZIP files as the input. The ZIP files must contain one JSON file per document to be created or updated. It also requires all the local files that need to be added to the media library (such as the image files).
Exporting your content
Go to settings: Import / Export
Click on “Export your documents”. The export module will send an email when the export is ready. Once it’s done, click on the provided link to download your archive.
NOTE: Only published documents will be exported. Drafts and releases can not be exported.
Preparing the JSON for import
The document data to be imported must be represented by a JSON file that has the same structure as an export JSON output file of the same custom type.
Make sure your document is not bigger than 250kB.
There are three types of document imports
The prismic.io import uses the filename of the imported file to detect which kind of import you want to do.
1 - Update an existing document
To update an existing document, you will use the document's ID as the filename.
Do do this you can export a document, change the JSON content, and import this document using the same filename.
2 - Import a new document or a new document (translation) group
To import new document or a new document group you will specify the filename as follows:
new_$GroupDocID_$LangIDThe new $GroupDocID is an arbitrary identifier that prismic will use to match a new document and its translations. It doesn't matter what this is, you can make up any combination of letters or numbers. Just be sure that you do not use an underscore, "_" in your $GroupDocID.
Make sure that all the documents in your document group use the same $GroupDocID. When uploaded, prismic.io will replace this $GroupDocID with its own $GroupLangID.
The $LangID is the Language ID that you can find in the Settings > Multi-language (for example "en-us" for English - United States)
3 - Import new translations
To import new translations for a document that is already in your repository, you will specify the filename as follows:
translate_$GroupLangID_$LangIDThe $GroupLangID is the identifier for a group of translations in prismic. You can find the $GroupLangIDof an existing document by exporting this document. You'll see the $GroupLangID in the file name.
The $LangID is the Language ID that you can find in the Settings > Multi-language (for example "fr-fr" for French - France)
An example
Here are the steps you need to take:
- Create a Document Custom Type that uses all existing prismic.io fields, or use this example.
- Publish a document of that type. Make sure to populate it with sample content using all editor formatting options (for a Rich Text field, for example).
- Create a snapshot of the repository using the Export feature from the Import page (/settings/import)
- The Export feature will create a ZIP file that contains a JSON file for each document contained in the repository. The JSON export files are named with the ID of the document (ex. VcidGCIAACIAX-sW.json)
Here is an example of the JSON file we get from exporting the full sample document we’ve manually populated.
You can refer to this output file syntax to generate the input JSON file for importing your new documents.
Assets
In the JSON import file, you must specify an original path (URL) for all the assets to be imported (such as images). The importer will download the resources from the provided urls and add them to your repository’s media library. If a given asset is used several times in one import batch, that asset will be added only once to the media library.
You can see an example on how to import an asset in your prismic.io media library.
"my-image": {
"origin": {
"url": "https://pbs.twimg.com/profile_images/770646787006861312/bX2KLhDL.jpg"
}
}Importing documents
The JSON documents for an import batch must be compressed in a zip file that is uploaded from the Import page.
It’s important that you select all your document and zip them. The JSON files should be at the root of the zip. There shouldn’t be a folder in the zip file.
When uploading the zip file, the import module will check the documents and warn the user if any of the JSON files contain any errors. All major errors have to be fixed before the import can be completed.
