Skip to content

Take System Snapshot

Captures the configuration of the Clarive instance at the moment the op runs and stores it as a snapshot, the same kind you get from the Take snapshot button under Admin, Snapshots. Each part of the configuration is dumped to YAML and kept inside the snapshot, which can later be exported as a zip or imported back, in whole or in part.

Reach for it when a rule is about to change something wide-reaching and you want a restore point: before a configuration import, or on a schedule the night before a release window. See Snapshots for what you can do with one afterwards.

This captures configuration, not data. Topics, jobs, job logs and artifacts are not in it.

snapshot record Title, User, time component dumped to YAML component dumped to YAML component dumped to YAML snapshot id returned any component fails: the whole snapshot is discarded

Fields

Title

The name the snapshot carries in the snapshot list. ${var} placeholders expand, so Before ${rule_name} on ${job_name} gives you a row you can recognise a month later.

Leave it blank and the snapshot is stored with no name on it. The list is ordered by date, so an untitled row is only identifiable by its timestamp.

The title also drives the file name of an export. Characters that are not letters, digits, - or _ are replaced, and runs of replacements are collapsed, so Before release 7.2 becomes Before_release_7_2. An untitled snapshot exports to a file with no name in front of the extension.

Components

Which parts of the configuration to capture. The list offers CIs, Rules, Roles, Configuration, Categories, Notifications and Calendars, and you can pick as many as you want.

Leave it empty and every component is captured. An empty box is not an empty selection here. Narrow it only when the snapshot is aimed at one thing, for example capturing Rules alone before a rule import.

Each component is dumped in full, not as a difference against the previous snapshot. Two snapshots of the same instance hold two complete copies, and the size shown in the snapshot list is the total across the components you picked. Taking a full snapshot on every job run will grow the database quickly.

Type into the box and the list also offers the variables declared in the system, shown as ${name}. Do not pick one. A variable entry is stored as a selection the snapshot does not recognise, and an unrecognised selection is skipped without a word, so a snapshot whose only selection was a variable is written with no components in it and no size. Nothing in the rule reports that. Pick components by name.

User

Who the snapshot is recorded as. This name appears in the snapshot list as the creator and is the only trace of who asked for it.

The control offers the users in the system alongside the variables declared for users. It also keeps whatever you type that matches neither, so a name that does not exist is stored as written. ${var} placeholders expand. The form will not save the op with this box empty, and an op carrying no user at all records the snapshot as clarive. Fill it with ${username} in a rule driven by a person and with a fixed name in a scheduled one.

Failure and what you get back

Components are captured one after another. If any one of them fails, the partly written snapshot is deleted and the error stops the rule, so you never end up with a snapshot that looks complete and is not. Wrap the op in TRY statement with CATCH statement when a failed snapshot should not end the job.

The op returns the id of the snapshot it took. Put a name in the op's Return Key property to capture it and a later op can record it on a topic or put it in a notification. There is no op that restores a snapshot; restoring is done from the admin screen.

Nothing is written to the job log, so a rule that takes snapshots leaves no evidence in the log beyond the op having run. Follow it with LOG Message when you want the id visible to whoever reads the job.

Snapshots are not undone on rollback, and a rolled-back job leaves its snapshot in place. That is usually what you want, since the snapshot is the thing you would restore from.

The rule waits while the dump runs, which on a large instance is not instant. Two rules taking a snapshot at the same time do not wait for each other and each gets its own record.

Combining with other ops

Put it in front of the change it protects: an import, a bulk update, anything driven by CODE that touches configuration.

Gate it so it does not run on every pass. IF var condition THEN on the environment or the job mode keeps snapshots to the runs that matter.

Capture the id and pass it to Send a notification so the people who would have to restore know that a restore point exists.

Examples

A restore point before a release job touches configuration.

Title        Before ${job_name}
Components   (empty, meaning all)
User         ${username}

A narrow snapshot of the rules only, taken by a scheduled rule.

Title        Nightly rules backup ${date}
Components   Rules
User         clarive

Capture categories and notifications before a workflow change, and keep the id.

Title        Pre-workflow-change ${topic_mid}
Components   Categories, Notifications
User         ${username}
Return Key   foo_snapshot