DataMasque Portal

Managing Ruleset Libraries

Overview

To access the ruleset libraries page, click the Ruleset Libraries Ruleset Libraries button button in the left navigation menu. This page lists the libraries in the active project, and allows searching by name.

Library list page

Add a new library

To add a library, click the Add Library button at the bottom right of the libraries page. This opens the library editor, where you can set the library's name, project and YAML content.

The library name must be unique within its project. Library names may be up to 255 characters long and must not contain slashes. A new name also cannot be .. or contain #, because no import or $ref can name it. A library from an earlier release that already has such a name keeps it.

In the Project field, choose the project in which to save the library (see Creating resources in a project). To move a saved library to another project, see Moving Resources.

Library editor

View and edit a library

To edit a library, click the edit Edit button icon next to the library you wish to modify. The library editor will open with the library's current YAML content.

Users who have view-only access (Mask Builders without the manage libraries permission) will see a view View button icon instead, which opens the library in read-only mode.

While a library is being edited, its validation status changes to unknown (shown as a question mark icon Unknown validation status). The library is revalidated when it is saved. If the library becomes invalid, any rulesets that depend on it will also become invalid.

The library editor uses the same YAML editor as the ruleset editor. Refer to Ruleset YAML editor for details on editor shortcuts, autocomplete, and formatting.

A library that defines a mask or task your license does not include is still valid, and can still be saved. Its status shows as an orange warning symbol, and the editor lists the unlicensed features at the top of the page (see License warnings in the web UI).

Delete a library

To delete a library, click the delete Delete button icon next to the library on the libraries page. You will be prompted for confirmation before the library is deleted.

A library that is imported by active rulesets or ruleset generation configurations cannot be deleted straight away: the delete is rejected and a dialog lists the dependents, counting both rulesets and ruleset generation configurations separately (for example "3 rulesets, 1 ruleset generation configuration"). Confirming with Force Delete deletes the library anyway.

Note: Force-deleting a library that is still in use marks every dependent — both rulesets and ruleset generation configurations that import it — invalid, as they can no longer resolve their $ref references to this library. Fixing or restoring the library re-validates the dependents automatically.

Push/Pull a library

This feature allows you to push the content of a library to a Git source code repository, and to pull the content of a library from a specific commit. Each library is managed independently as its own Git unit.

Tip: For an end-to-end walkthrough of first-time setup, see the Git integration setup how-to.

Prerequisites

  • You must have configured a Git repository where you want to push and pull library files. Refer to Git Repository Settings.
  • You must have uploaded your Git SSH key on the My Account page. Refer to Git SSH Key Information.
  • The library must have a name specified.
  • To push a library, you must be an administrator, or a Mask Builder with the Manage Ruleset Libraries permission. Other Mask Builders can pull libraries, but the Push button is disabled for them. Refer to Permissions.

Push a library

To push a library file to the remote repository, follow these steps:

  1. Click the Git button to open the Push/Pull Library dialog, and navigate to the Push tab.
  2. The dialog displays the full remote path that the library will be pushed to, in a folder named for the library's project (e.g. /fol1/fol2/libraries/Sales/emails.yml for the library emails in the project Sales). Some libraries that existed before projects keep their old file: see Git file locations. If you have changed the library's name, save it first: until then, the dialog shows why the library cannot be pushed.
  3. Enter the commit message in the provided field.
  4. Click the Push button to proceed. The current content of the YAML editor will be pushed to the remote repository.

Note that at least one change to the library YAML is required for the push to succeed. DataMasque will reject any attempt to push a library that is identical to the latest version in the repository. A push that needs a folder where the repository has a file of that name fails with an error naming the path. Each file belongs to one library: a push to a file that another library uses fails with an error naming that library. Rename one of them, or move it to another project.

Push Library

Pull a library

To fetch the content of a library file from the remote repository at a specified path and commit, follow these steps:

  1. Click the Git button to open the Push/Pull Library dialog, and navigate to the Pull tab.
  2. In the dropdown box, you will see a list of library files organised by project folder under the libraries/ directory. Only files with .yml or .yaml extensions are shown. Choose the desired file, and the commit versions for that file will be displayed in the table below. You can reload the file list and commit versions by clicking the Refresh Git Commits button.
  3. Choose the desired version of the selected file from the list.
  4. Optionally, check the checkbox to overwrite the current library name, and for a new library its project. The name comes from the selected file, and a new library's project from its folder (e.g. selecting libraries/Sales/emails.yml sets the name to emails and the project to Sales). A saved library keeps its project, so only its name is overwritten. When pulling into a new blank library, this option is always enabled and cannot be unchecked, and the project picker is set to the project the folder names, if there is one, or else cleared for you to choose. A file directly in libraries/ leaves the picker as it is. A pull never creates a project.
  5. Click the Pull button.
  6. Upon a successful pull operation, the content of the selected remote file version will replace the existing content in the YAML editor. A saved library stays in its project. A pull of a file outside a project folder, such as one directly in libraries/ or in a folder from before projects, shows a warning that the library's references may need checking.

Pull Library