DataMasque Portal

Bulk Ruleset Management

Overview

The Ruleset Management page allows you to export, import, and delete rulesets in bulk. To access this page, choose the Ruleset Management item from the main menu.

This is useful for transferring rulesets between DataMasque instances (e.g. from a development environment to production), or for backing up and restoring rulesets. Any ruleset libraries used by the exported rulesets are also included in the export.

Exporting rulesets

To export rulesets, select one or more rulesets using the checkboxes in the table, then click the Export button at the bottom of the page.

Any ruleset libraries referenced by the selected rulesets are automatically included in the export. When exporting all rulesets, all active libraries are included.

Check the Include seed files option to include any custom seed files referenced by the selected rulesets in the export archive. Built-in DataMasque seed files (prefixed with DataMasque_) are not included, as they are already available on all DataMasque installations. Each seed file is included once, from the project a masking run would read it from:

  • A seed file named with its project, such as payments/names.csv, is the one in that project. The project name is matched ignoring case.
  • A seed file named by its name alone, such as names.csv, in a ruleset is the one in the ruleset's project.
  • A seed file named by its name alone in a library is the one in the project of each exported ruleset that imports the library, or in the library's own project when no exported ruleset imports it.

A seed file that a project holds under a name starting with DataMasque_, from an earlier version of DataMasque, is included, but cannot be imported; rename it before exporting.

The export will download a Zip archive containing the selected rulesets and their libraries in YAML format. The archive records the project of each ruleset, library and seed file, so importing it keeps each one in the project of the same name. This archive can be imported to any DataMasque instance using the import feature described below, or via the POST /api/import/v2/ API endpoint.

Importing rulesets

To import rulesets, click the Import icon in the top-right corner of the Ruleset Management page. A dialog will appear where you can upload a Zip archive previously exported from DataMasque.

Each item is imported into the project the archive names for it, which is created if it does not exist. Creating a project requires an administrator: for any other user, an archive that names a project that does not exist fails to import, and nothing is imported. Some archives name no project for some of their items, such as one exported by an older version of DataMasque or by the Version 1 export API, which names none for its rulesets and seed files, or for libraries without a namespace. For such an archive, or one the dialog cannot read, the dialog shows a Project field, set to the current project, and those items are imported into the project chosen there. Under All projects, the field starts empty when there is more than one project, and Import is enabled once a project is chosen.

Import an older archive into Default unless its rulesets belonged elsewhere. An older archive keeps the library names it was exported with, so update its references if the upgrade renamed a project.

An item with the ID of an existing ruleset or library matches that item, wherever it is, and Duplicate handling below decides what happens to it. A ruleset it replaces or restores stays in its project, and a library it replaces or restores moves to the project it is imported into. Otherwise, items are only matched against existing items in the project they are imported into.

Duplicate handling

The import dialog provides a Duplicate Handling section that controls how each resource type is handled when a matching item already exists. Each resource type (Rulesets, Ruleset Libraries, and Seed Files) has a dropdown with two options:

  • Replace current — any existing item that matches an imported item will be updated with the imported content.
  • Skip — existing items are left unchanged and the imported item is skipped.

The default setting is Replace current for Rulesets, and Skip for Ruleset Libraries and Seed Files.

Some names cannot be imported, and the results summary reports each item that has one as an error:

  • a seed file whose name starts with DataMasque_, because that prefix is reserved for built-in seed files;
  • a new ruleset with / in its name, because a reference uses / to separate the project from the name;
  • a new library named .. or with # in its name, because no import or $ref can name it.

A ruleset or library that already exists with such a name is updated as usual.

Note: Archived rulesets and libraries (those that were previously deleted but retained due to run history) are always restored when they match an imported item, regardless of the duplicate handling setting.

How rulesets are matched

When importing from an archive that was exported from DataMasque, each ruleset is matched against existing rulesets by its original ID first, then by name if no ID match is found.

This means if you export a ruleset from one instance and import it to another, then later re-import an updated version, it will correctly update the same ruleset even if it has been renamed on the destination instance.

When importing from a manually created Zip archive (without a manifest.json), matching is done by name only.

How libraries are matched

When importing from an archive that was exported from DataMasque, each library is matched against existing libraries by its original ID first, then by project and name if no ID match is found. An archive exported by an older version of DataMasque names a namespace instead of a project, so its libraries are matched by namespace and name.

When importing from a manually created Zip archive (without a manifest.json), matching is done by namespace and name only.

Import results

After the import completes, a results summary is displayed showing what happened to each ruleset, library, and seed file. The Project column shows the project each item was imported into. When some items named no project, the summary also names the project they were imported into. You can download this summary as a CSV report using the Download Report button.

Each item will have one of the following statuses:

Status Description
Created No existing match was found, so a new item was created.
Updated An existing match was found and overwritten with the imported content.
Skipped An existing match was found, but overwrite was disabled so it was left unchanged.
Not Created An existing match was found with identical content, so no changes were needed.
Restored A previously deleted (archived) ruleset or library was restored and updated.
Error The import failed for this item. Check the message for details.

A ruleset can be Created, Updated or Restored and still be invalid, so check its message and its status on the Rulesets page.

A successful import would look like this:

Import results

Deleting rulesets

To delete rulesets, select one or more rulesets using the checkboxes in the table, then click the Delete button at the bottom of the page. You will be prompted to confirm the action.

Note: Rulesets that have associated run history cannot be permanently deleted. They will be archived instead, which removes them from the ruleset list but preserves the run history for reference.