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.

A common operational need is to keep multiple deployment environments in sync with each other. For example:

PurposeExample
Separate by user
  • Developer 1 environment
  • Developer 2 environment
Separate by purpose
  • QA environment
  • Production environment

For Uniform, this is done using serialization of project assets, such as Uniform Canvas components or compositions and 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.

There is a single command to backup & restore all project assets:

uniform sync pull --config ./uniform.config.ts

The Uniform CLI also provides the ability to granularly backup and restore the following project assets:

CategoryType
CanvasComponents
CanvasCompositions & patterns
CanvasData types
CanvasCategories
ContextAudiences & intents
ContextEnrichments
ContextQuirks
ContextSignals
ContextTests
IntegrationDefinitions
Project mapDefinitions
Project mapNodes
RedirectDefinitions

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.

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.

  1. 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/cli

  2. Make sure you have a .env file with the values needed to connect to your Uniform project.

    UNIFORM_API_KEY=<YOUR API KEY> UNIFORM_PROJECT_ID=<YOUR PROJECT ID>

  3. Add Configuration file uniform.config.ts to 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: { composition: { push: { // May be useful to only create new compositions and not update existing ones to avoid accidental overrides mode: 'create' } }, pattern: {}, category: {}, component: {}, dataType: {}, signal: {}, test: {}, aggregate: {}, enrichment: {}, quirk: {}, projectMapDefinition: {}, projectMapNode: {}, redirect: {}, } } }; module.exports = config;

  4. Add the following scripts to your package.json file:

    package.json

    { "name": "my-package", "version": "0.1.0", "private": true, "scripts": { "pull": "uniform sync pull", "push": "uniform sync push" }, "devDependencies": { "@uniformdev/cli": "latest" } }

  5. To backup the assets in your Uniform project, run the following command.

    Backup project assets

    npm run pull

    About this step

    A file for each project asset is created in the sub folders under the folder data.

  6. To restore the assets to your Uniform project, run the following command:

    Restore project assets

    npm run push

    About this step

    Project assets stored in the sub folders under the folder data are 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.

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, specify a filename instead of an output directory in configuration filename property:

uniform.config.js

module.exports = { serialization: { entitiesConfig: { composition: {}, component: { directory: './uniform-data/components.yaml' } } } }

To add multiple types of product assets to a single file, change global directory property to filename with yaml or json extension:

uniform.config.js

module.exports = { serialization: { entitiesConfig: { composition: {}, component: {} }, directory: './uniform-data.json' } }

Learn more about working with the with the manifest.

Last modified
Next
Troubleshooting