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

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.

View and edit a library
To edit a library,
click the edit
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
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
).
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
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$refreferences 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 Accountpage. 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:
- Click the Git button to open the Push/Pull Library dialog, and navigate to the Push tab.
- 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.ymlfor the libraryemailsin the projectSales). 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. - Enter the commit message in the provided field.
- 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.

Pull a library
To fetch the content of a library file from the remote repository at a specified path and commit, follow these steps:
- Click the Git button to open the Push/Pull Library dialog, and navigate to the Pull tab.
- In the dropdown box, you will see a list of library files organised by project folder
under the
libraries/directory. Only files with.ymlor.yamlextensions 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
button. - Choose the desired version of the selected file from the list.
- 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.ymlsets the name toemailsand the project toSales). 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 inlibraries/leaves the picker as it is. A pull never creates a project. - Click the Pull button.
- 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.
