Common tasks
Many of the kinds of administrative tasks you perform using the Uniform dashboard or the CLI can also be done programmatically using the Uniform APIs.
Backup and restore#
Why backup and restore?#
A common operational need is to keep multiple deployment environments in sync with each other. For example:
| Purpose | Example |
|---|---|
| Separate by user |
|
| Separate by purpose |
|
For Uniform, this is done using serialization of project entities, such as Uniform Canvas components, compositions, Uniform Context signals, and enrichments, to files on disk. These files can then be committed to source control and shared between environments, or used to scaffold templates and demos.
Which project entities can you backup & restore?#
Sync command#
There is a single command to backup & restore all project entities:
Sync specific project entities#
The Uniform CLI also provides the ability to granularly backup and restore the following project entities:
| Category | Type |
|---|---|
| Canvas | Assets |
| Canvas | Components |
| Canvas | Compositions |
| Canvas | Component patterns |
| Canvas | Composition patterns |
| Canvas | Categories |
| Canvas | Content types |
| Canvas | Entries |
| Canvas | Entry patterns |
| Canvas | Data sources |
| Canvas | Data types |
| Canvas | Labels |
| Canvas | Locales |
| Canvas | Preview URLs |
| Canvas | Preview viewport |
| Canvas | Workflow |
| Context | Audiences & intents |
| Context | Enrichments |
| Context | Quirks |
| Context | Signals |
| Context | Tests |
| Integration | Definitions |
| Project map | Definitions |
| Project map | Nodes |
| Policy documents | Definitions |
| Redirect | Definitions |
| Webhook | Definitions |
tip
Data sources cannot be synced because they generally contain secrets that should not be written to files.
Data sources may be directly created using the CLI, for the purposes of scaffolding them if they do not contain secrets.
Automate backup & restore#
This section describes how to add backup and restore scripts to a Node project. Your CI/CD process can trigger the script to automate backup & restore.
Prerequisites
These instructions assume you already have a Node project and a Uniform project.
Make sure the following dependencies are included in your Node project. If you need to add them, you can add them as developer dependencies:
@uniformdev/cliMake sure you have a
.envfile with the values needed to connect to your Uniform project.UNIFORM_API_KEY=<YOUR API KEY> UNIFORM_PROJECT_ID=<YOUR PROJECT ID>Add Configuration file
uniform.config.tsto the root of your project (you can find configuration schema here):uniform.config.ts
import type { CLIConfiguration } from '@uniformdev/cli'; require('dotenv').config(); const config: CLIConfiguration = { serialization: { format: "yaml", mode: "mirror", directory: "./uniform-data", entitiesConfig: { asset: {}, composition: { push: { // May be useful to only create new compositions and not update existing ones to avoid accidental overrides mode: 'create' } }, component: {}, componentPattern: {}, category: {}, contentType: {}, entry: {}, entryPattern: {}, dataType: {}, signal: {}, test: {}, aggregate: {}, enrichment: {}, locale: {}, quirk: {}, projectMapDefinition: {}, projectMapNode: {}, redirect: {}, workflow: {}, } } }; module.exports = config;Add the following scripts to your
package.jsonfile:package.json
{ "name": "my-package", "version": "0.1.0", "private": true, "scripts": { "pull": "uniform sync pull", "push": "uniform sync push" }, "devDependencies": { "@uniformdev/cli": "latest" } }To backup the entities in your Uniform project, run the following command.
Backup project entities
npm run pullAbout this step
A file for each project entity is created in the sub folders under the folder
uniform-data.To restore the entities to your Uniform project, run the following command:
Restore project entities
npm run pushAbout this step
Project entities stored in the sub folders under the folder
uniform-dataare restored to your Uniform project.
tip
Another useful technique with pushing and pulling is to perform bulk updates. Since the serialized files are plain YAML (or JSON), you can use your favorite tools such as jq to modify them before pushing them back into Uniform.
Backup entities as JSON files#
To write JSON files instead of YAML, set format to json. The layout stays the same, with one file for each project entity:
uniform.config.js
uniform sync pull creates these files:
Backup entities to a single file#
For CI/CD environments it's best to produce a single artifact instead of many serialized files to define the state of Uniform. To support this, the Uniform CLI allows you to use the pull and push commands directly to a package file instead of multiple files on disk.
To use this feature, set the directory property of an entity type to a filename with a .yaml, .yml, or .json extension:
uniform.config.js
All components go into one file, and compositions keep the default layout of one file each:
To add multiple entity types to a single file, change the global directory property to a filename with a .yaml, .yml, or .json extension:
uniform.config.js
Components and compositions both go into uniform-data.json, each in its own section. A pull replaces only the section for the entity type it pulls and keeps the other sections. This also applies when you pull one entity type into an existing package file, for example with uniform canvas component pull ./uniform-data.json.
To give each entity type its own file, set directory on every type. This example writes JSON files: