WP Engine Atlas Blueprints

Blueprints describe data to be imported by an automated process. They help to rapidly restore WordPress state and post entries to accelerate user onboarding.

Blueprints can be exported and imported using WP-CLI commands available in the WP Engine Atlas Headless Extension plugin:

• wp atlas blueprint export will dump the current state of your site to a blueprint zip file.
• wp atlas blueprint import https://example.com/path/to/blueprint.zip will import a blueprint from a publicly-accessible URL.
• wp atlas blueprint import /filesystem/path/to/blueprint.zip will import a blueprint from a local file path.

Blueprint files

A blueprint is a zip file containing:

• A required main.json manifest listing data and content for the blueprint import process to restore.
• An optional media/ folder containing images linked to post entries. This includes featured images (posts with _thumbnail_id post meta) and files attached to ACF media fields.

Blueprint contents

Blueprints can hold:

• ACF post types and field groups.
• ACF taxonomies.
• Terms relating to ACF taxonomies.
• Posts, including ACF entries and WordPress core post and page types by default.
• Tags applied to posts.
• Post meta relating to posts.
• Media files and data used in posts.

Not yet supported

Atlas blueprints do not yet export or import:

• Post authors: All posts are assigned to the current user on import.
• Installed plugins: This plugin does not yet install or activate plugins.

If you’d like to see support for these please open or add to a discussion.

Blueprint troubleshooting

Blueprint export can fail for these reasons:

Error	Solution
The manifest has a missing or empty blueprint.name property	Check the blueprint’s main.json file for a blueprint.name property.
The manifest blueprint.name resulted in an empty folder name.	Check to ensure the blueprint.name in main.json (or the name override provided via the --name flag via WP-CLI) contains at least one alphanumeric character.
Error saving temporary file	The manifest could not be written. Check disk space and file permissions.
Unable to create blueprint zip file. ZipArchive not available.	This plugin needs the ZipArchive PHP core library to write zip files. You will need to enable this via your web host or local PHP configuration to create Atlas blueprints.
Unable to create blueprint zip file.	Check disk space and file permissions.
Could not add manifest to zip file.	Check disk space and file permissions.
Could not add media to zip file.	Check disk space and file permissions.
Could not save blueprint zip file.	Check disk space and file permissions.

Blueprint import can fail for these reasons:

Error	Solution
Please provide a URL to a blueprint zip file.	Provide a URL to a publicly-accessible blueprint zip file.
[Any HTTP fetch error]	Check the blueprint zip URL is publicly accessible from your web browser and try again.
Received unexpected error downloading zip.	Check that the blueprint zip URL is publicly accessible from your web browser and try again.
Received empty response body.	Check tho ensure the blueprint zip URL is not corrupt by downloading it with your web browser.
Error saving temporary file	Check disk space and file permissions.
Error saving file	Check disk space and file permissions.
Provided file type is not supported.	Confirm that the provided URL points to a zip file.
Could not read blueprint file	Confirm that the blueprint file unzips. Check disk space and file permissions.
Could not read a main.json file in the blueprint folder.	Confirm that the blueprint zip contains a file named main.json in the blueprint root folder when unzipped.
main.json is missing the required services.wordpress property.	Check that the main.json manifest contains a services.wordpress property.
main.json requires an ACF version of x but the current ACF version is y.	Update ACF to the requested version.
main.json requires a WordPress version of x but the current WordPress version is y.	Update WordPress to the requested version.
main.json is missing the required services.wordpress.plugins.faustwp property.	Update the main.json to include the required property.
The FaustWP plugin is required but is not active on this site.	Install and activate the FaustWP plugin from wordpress.org.
main.json requires a FaustWP version of x but the current FaustWP version is y.	Update the FaustWP plugin to the requested version.
The WPGraphQL for ACF plugin is required but is not active on this site.	Install and activate the required WPGraphQL for ACF plugin.
main.json requires a WPGraphQL for ACF version of x but the current WPGraphQL for ACF version is y.	Update the WPGraphQL for ACF plugin to the required version.
Could not read media file at x	Check to ensure the blueprint zip contains media files. Check disk space and file permissions.

Blueprint import can also generate a warning (but still succeed):

Warning	Meaning
“Taxonomy exists” or similar	A taxonomy from the blueprint already exists on your site. This plugin will not attempt to re-import it.
“Term exists” or similar	A term from the blueprint already exists on your site. This plugin will not attempt to re-import it.
“Tag exists” or similar	A tag from the blueprint is already assigned to a post. This plugin will not attempt to re-assign it.