Catalogs

Catalogs

Use a catalog when templates and reusable content should move, release, or upgrade together. A catalog can contain templates, attributes, code lists, stencils, themes, fonts, and images.

Understand catalog types

• Authored catalogs are owned and edited by the current tenant. Create one for shared templates, a common design system, or a controlled release.
• Subscribed catalogs are installed copies from another source. Their resources are available to use, but read-only in the receiving tenant.
• System catalogs provide bundled resources such as locale, language, and country code lists. They are also read-only.

When a team needs to change subscribed content, make the change in its authored source catalog and release a new version. Do not copy the resource into the receiving tenant unless it should become independently maintained.

Create and release a catalog

1. Open Catalogs and choose New Catalog.
2. Add the templates and reusable resources that belong together.
3. Check previews, examples, and resource dependencies.
4. Choose Release new version and enter the next semantic version.
5. Share the released catalog with another tenant or export it as a ZIP.

A release is an immutable boundary for the catalog’s current content. An Authored catalog can continue as a working copy afterwards; release again deliberately when its next set of changes is ready.

Subscribe to a remote catalog

1. Open Catalogs and choose Subscribe.
2. Enter the URL of the catalog manifest and its authentication details when required.
3. Browse the available resources, then choose Install for selected resources or Install All.
4. Use Check for updates when the source publishes a new release.
5. Review the upgrade preview before applying it.

The subscribed catalog and its installed resources are read-only. A URL-backed subscription can check its source for updates; a ZIP-managed subscribed catalog is upgraded by importing a newer ZIP instead.

Import and export

Export a catalog

1. Open Catalogs in the source tenant.
2. Open the catalog you want to transfer.
3. Choose Export and download the ZIP file.
4. Keep the ZIP with the release notes or deployment artifact.

The export contains the catalog’s current resources and manifest. If an authored catalog has changes since its last release, the export is marked as a development version so that it is not mistaken for a released version.

Import a catalog

1. Open Catalogs in the target tenant and choose Import.
2. Upload the catalog ZIP.
3. Choose the catalog type:
   • Authored creates an editable catalog owned by this tenant.
   • Subscribed creates a read-only catalog managed as a published copy.
4. If an Authored catalog with the same slug already exists, choose how to handle it:
   • Merge updates resources from the ZIP and keeps local-only resources.
   • Replace makes the catalog exactly match the ZIP and removes local-only resources.
5. Review any validation or conflict messages and confirm the import.
6. Preview important templates after the import.

An import into a new Authored catalog can adopt the ZIP’s clean release version. Importing into an existing Authored catalog changes its working copy; it does not silently create a release. Release it deliberately when the content is ready.

Importing a newer ZIP into a Subscribed catalog is an upgrade. Epistola checks conflicts before changing anything and leaves the previous version intact if an item cannot be installed, so you can fix the problem and retry.

Good practice

Use an Authored catalog to maintain and release reusable content, then share it as a Subscribed catalog in another tenant. Use a ZIP export for a one-off transfer, backup, recovery, or project handover. Always preview templates and verify their dependencies after importing.