Skip to main content

How to add a custom mask

Learn how to add a custom mask to a built-in data type


Masks reduce data exposure by replacing meaningful parts of a data item with a filler character. For example, a credit card number might be masked so only the first four digits could be read, such as "9734-—****."

Piiano Vault offers several built-in masks, each associated with a built-in data type. The types with built-in masks include SSN, EMAIL, and CC_NUMBER. You can learn more about these built-in types and masks from the Built-in transformations guide.

You enhance the built-in functionality by creating masks that complement the built-in masks or provide masks for data types that don't have a built-in option. You create masks using JavaScript code that defines how a mask is applied to an item of data. Then, you install this JavaScript using a bundle and link the mask function to a built-in data type. The mask can then be used by the built-in type or any custom data type based on it.

Check out the Get transformed properties for all objects in a collection section of the List all objects guide to see how you use masks.

In this tutorial, you learn how to add a simple mask to the built-in type NAME. The same process applies to more complex functions and other types, including custom types.


If your custom JavaScript code is self-contained, as this example is, you can use the JavaScript file as the bundle file without needing to build the bundle. For details on building a bundle with dependencies, refer to the bundles documentation.

This tutorial covers:

  1. Adding the code files that contain the mask
  2. Uploading the code to Vault
  3. Connecting the mask function to a built-in type
  4. Testing the mask


  1. A running Vault
  2. The command line tool installed
  3. Vault Javascript support must not be disabled (it is enabled by default and can be disabled with an environment variable PVAULT_FEATURES_DISABLE_JAVASCRIPT)

Add the code

First, write the code that applies the mask. In this case, code that accepts a string and replaces all the string's characters with * except for the first one.

// export the masking function to be used by the Vault
exports = {
"mask" : {
type: "transformer",
description: "Name mask - keep only the first character",
handler: name_mask

// masks a name by replacing all charachters with "*" except for the first one
function name_mask(context, object, value) {
if (value.length === 0) { // can not mask an empty name
return "";
return value.charAt(0) + "*".repeat(value.length - 1);

Create a file and add this code to it. Save the file with the name main.js

Upload the code to Vault

To upload your code you use the CLI like this:

pvault bundle add --name name_mask --description "mask for NAME" --bundle-code @./main.js
| description | creation_time | name | normalizers | validators | transformers |
| mask for NAME | Tue, 26 Mar 2024 15:29:01 UTC | name_mask | [] | [] | [mask] |

The bundle name can not contain -.

Connect the mask to the datatype NAME

To connect the mask to the data type NAME, use the CLI like this:

pvault datatype update --name NAME --datatype-update-json '{ "custom_transformers": [ "name_mask.mask" ] }'

You get a response similar to this:

| description | validator | creation_time | name | base_type_name | normalizer | default_transformer | transformers |
| A string containing a name. | | Sun, 14 May 2023 00:00:00 UTC | NAME | | | | [token name_mask.mask] |

Test the mask

Use the Piiano Vault sample data to test your new mask, like this:

pvault collection add --collection-template persons --add-test-data -c Persons
pvault object list -c Persons -p email,first_name,last_name
# and now with the masks
pvault object list -c Persons -p email.mask,first_name.mask,last_name.mask

You get this response for the sample data (masking both the first name and last name):

| email.mask | first_name.mask | last_name.mask |
| R********** | R**** | D**** |
| K**************** | K**** | S****** |
| J**************** | J***** | W***** |
| A************** | A***** | R****** |
| L******* | L****** | B***** |
| D********* | D******* | F******* |
| Q************ | M*** | S****** |
| E********** | E**** | J**** |
| A************ | A**** | P**** |
| j******* | J*** | D** |